Node.js on dwmkerr.com

mongo-monitor - a simple CLI to monitor your MongoDB cluster

Wed, 16 May 2018 20:09:53 +0000

The mongo-monitor CLI is a lean and simple tool to check the status of a MongoDB server or cluster. The code is on GitHub:

github.com/dwmkerr/mongo-monitor

Here’s how it looks in action:

In this animation I am monitoring a simple sharded cluster, and running some example maintenance operations, adding a node to a replicaset, stepping down a primary and shutting down a replicaset node.

A simple CLI which shows the status in real-time can be very useful to keep open when performing admin, letting you see how your changes affect the cluster as you work on it.

Installing the CLI

The CLI is installed with npm:

npm install -g mongo-monitor

Connecting to a Cluster

Connect to a cluster by providing a connection string. The tool uses mongo-connection-string to parse the connection string, so you can be flexible with the input:

# Connect to a local instance
mongo-monitor localhost:27107

# Connect to a remote replicaset, authenticated
mongo-monitor admin:P@sswrd@mdbnode1,mdbnode2,mdbnode3?replicaSet=rs

Once a connection is established, the tool will periodically check the status of the cluster. If the cluster is sharded, it will also inspect each individual replicaset.

Replicaset Status

Here’s the kind of output you might get from a replicaset:

The name of the replicaset is shown, along with each member. The status of each member is also shown, updating automatically every second.

This is convenient when administering replicasets, stepping down a master, adding or removing nodes and so on.

Sharded Cluster Status

When connecting to a sharded cluster, you will get output like this:

Each shard is shown, along with the details of the replicaset which make it up.

Keeping a view like this open is useful when administering sharded clusters, adding or removing shards, desharding, updating the replicasets which make up shards and so on.

Get Involved!

If you like the tool, check out the code and feel free to make pull requests with additions! There are a few issues on the project already, and there are all sorts of features I’d love to add but haven’t had the time, such as:

Being able to see the lag for replicaset members, to see if secondaries are falling behind
Being able to perform replicaset operations directly from the tool
Showing the priorities of nodes if they are not the default

All ideas are welcome, let me know in the comments or repo, and share the tool if you find it useful!

A utility to help you wait for ports to open

Thu, 25 May 2017 22:15:00 +0000

There are occasions where you might need to have scripts or commands which wait for TCP/IP ports to open before you continue.

I’ve come across this need again and again when working with microservices, to make my life easier I’ve created a little utility called wait-port which will wait for a port to open:

It’s built in Node, the project is open source, open for contributions and ready to use:

github.com/dwmkerr/wait-port

Installation and usage is pretty straightforward:

$ npm install -g wait-port
wait-port@0.1.4
$ wait-port 8080
Waiting for localhost:8080.....
Connected!

You can also install locally¹.

This might be useful if you have a docker-compose workflow where you need to wait for a database to start up, want to run some automated tests against a server which can be slow to start, or have a complex set of interdependent services which need to start up in a specific order.

I’d be interested to know of any cases where people find this useful, so please share in the comments and I can add a ‘use cases’ section to the project showing others how they might be able to save some time and energy with the utility!

The Pure Shell Way

It is actually pretty easy to do this purely in bash. Here’s how you can wait for a port to open in a shell script:

until nc -w 10 127.0.0.1 3000; do sleep 1; done

This will be sufficient in many cases, the reason I created the utility is:

I want something which is very readable in scripts (wait-port 3000 to me is more readable).
I want to be able to specify an overall timeout (i.e. wait for up to 60 seconds) which requires adding more to the script.
I need a different error code if the overall attempt to wait times out or fails for an unknown reason.
I want to be able to optionally show some kind of progress (you can use the --output flag to control the output from wait-port).
I know I need a few other features (being able to ‘snooze’ after the port is opening, i.e. waiting for a little extra time, controllable intervals for trying the port etc, all of which can be easily added).

Testing Tip!

One really useful tip which will be obvious to *nix pros but I wasn’t aware of is that you can create a server listening on a port with netcat:

nc -l 8080

This is just the barest basics of what netcat can do, it’s a very powerful tool. This tip makes it very easy to test the wait-port behaviour.

Footnotes

I hate installing things globally, if you are like me you’ll prefer local usage with something like: npm install wait-port && ./node_modules/.bin/wait-port :3000 ↩︎

Using Slack for Server Development

Fri, 18 Nov 2016 01:25:00 +0000

I recently found a surprisingly helpful approach for server-side development which uses Slack in a creative way.

The Problem

The scenario can be roughly simplified to this:

We are building a mobile app and application server. This will take data from a user, transform it and then pass it to the enterprise system processing.

The problem is that the enterprise system doesn’t exist yet!

Now this is not too much of a challenge, the first thing we did was build a simple mock of the enterprise system in Node.js, so that we can at least talk to something:

So now we have the question - is our application server transforming the data correctly?

Let’s say that in our example we bring in three pieces of data from the UI - a first name, middle name and last name.

Our enterprise system, in this case we’ll say it is a CRM system, only accepts a first name and last name. So in our app server, we are going to concatenate the middle name and last name.

Our testers want to make sure that the enterprise system will receive the right data - but at the moment it is only a mock, we cannot log in a check the middle and last names have been combined properly. What to do?

Slack to the Rescue!

It’s a trivial change to our mock server to send the received messages to Slack:

Now our testers can input data in the mobile app and then watch a slack channel to see the data our application server will actually send to the enterprise system. They can verify the logic has been implemented correctly.

Here’s how it might look - in the image below I am running my mock enterprise server, which has Swagger UI to show the mocked APIs and allow me to call them:

The message is received on the server, sent to slack and we can check the result:

Now this is obviously a trivial and contrived example, but Slack offers a lot of capabilities. Imagine you have a server which watermarks images, you could send an image file to render to the screen. There are a whole bunch of ways you can extend this use case.

In the early stages of a project, where they may be many mocked systems, being able to see what they are doing can be really useful.

Setting it up

I’ve created a super-simple demo setup here:

github.com/dwmkerr/slack-backend

Here’s how you go about it.

Step 1: Set up a webhook on slack

Step 2: Use the HTTP APIs from Slack, or a client from your platform of choice to send the message:


// Create the Slack webhook based on our config.
const slack = new Slack();
slack.setWebhook("https://hooks.slack.com/services/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");

// Every time we're about to handle a request, tell our friend Slack.
server.ext('onPreHandler', (request, reply) => {

 // Never bother logging any requests to swagger UI.
 if(request.path.match(/\/swaggerui\//) ||
 request.path.match(/\/swagger.json/) ||
 request.path.match(/\/$/)) {
 return reply.continue();
 }

 // Send the Slack message.
 slack.webhook({
 text:
`Request *${request.id}*
\`\`\`${request.method} ${request.path}

${JSON.stringify(request.payload, null, 2)}
\`\`\``
 });

 reply.continue();
});

This approach was quick and easy to implement, hopefully others will find it useful!

Effective Node.js Debugging

Sat, 03 Sep 2016 01:36:09 +0000

If you are interested in improving your Node.js debugging skills, then check out my talk at the recent JSChannel 2016 conference in Bangalore:

Comments and observations are always welcome!

Testing the Docker for Mac Beta

Fri, 03 Jun 2016 10:45:24 +0000

I’ve finally had a chance to install the new Docker for Mac Beta and give it a whirl. In this article I’m going to talk a bit about how Docker works, the challenges of running Docker on a Mac or Windows and how the new Beta helps.

Below: The welcome message for the new Docker for Mac app

So What is Docker for Mac?

If you don’t know what Docker is, check out my article Learn Docker by Building a Microservice or the lovely What is Docker page from the docs.

You may be aware that Docker creates processes in isolated containers using some key Linux technologies which allow for low-level isolation (such as namespaces and cgroups¹).

This is described in detail on the Understand the Docker Architecture page, but essentially means we can do this:

Here I have:

My machine, called Dave-Ubuntu, which is running Ubuntu², with a local IP 192.168.0.1.
The docker executable, which I use to issue commands to…
…the Docker Host, which runs the docker daemon, which actually does the work of starting/stopping/building containers and so on.
Some containers in the Docker Host - one is based on a MySQL image and has a DB, one is based on a Node.js image and is running an app.

The Docker host is actually my machine - I can connect using the loopback IP 127.0.0.1 (i.e. localhost). The containers also have the IP of the host. If I want to create and connect to a MySQL DB from my machine, I just type:

docker run -d -e MYSQL_ROOT_PASSWORD=123 -p 3306:3306 mysql
mysql -uroot -p123 -h127.0.0.1
> show databases;
> ...etc...
> exit;

The container was created on my machine (in the host) and addressable using my loopback IP.

So What?

This is all great, but things get a little harder on a Mac or Windows. MacOS and the Windows OS don’t have the same kernel level support for process isolation, control groups and so on, so the Docker Host cannot run on these operating systems. Instead, an extra layer and component is introduced:

What’s new?

Oracle VirtualBox has been installed to create and manage virtual machines.
A virtual machine running Linux (called in this case a ‘docker machine’) called ‘default’ has been created (by convention with the IP 192.168.99.100).
This virtual machine runs Linux, so can perfectly happily act as the docker host.
The docker host is still addressable as 127.0.0.1 - from the virtual machine - from the outside world (i.e. my Mac) I have to use the virtual machine IP.

So this is how Docker works on a Mac or on Windows. Things are made seemless where possible, for example, all of the required components are installed when you install the Docker Toolbox.

So What?

Well the problem here is that one of the big benefits of using docker is that it allows us to create development environments which are much closer to production environments (at least from a software point of view).

This kind of breaks down if we are doing development on a Mac or on Windows - because we have introduced an additional component which is simply not going to be present in our production environment. What are the problems?

1. Localhost vs docker-machine IP

Docker helps us be a lot more agnostic to our development box, but if I’m writing about how to interact with docker containers there’s a problem:

docker run -d -p 8080:8080 my-app-server
curl http://localhost:8080/some-api-call

This works on a Linux machine - it does not work on a Mac or Windows. On a Mac I need to run something like:

docker run -d -p 8080:8080 my-app-server
curl http://$(docker-machine ip default)/some-api-call

This will not work on Linux or Windows.

Is this a big deal? Actually, kind of. What if I have an integration test which spins up some containers and runs calls against them - the test has to know about the execution environment. That’s a pain. An alternative is to run tests in a container and link them with something like docker-compose, but this is not ideal.

2. Terminal Hassle

If I open a terminal and check to see what containers are running:

docker ps

I’ll see nothing. If I try to run a container:

docker run -it mongo

I’ll get an error - because my docker instance cannot communicate with the host. I need to use a specially set up terminal to tell it to connect to the VM.

Again, the Docker Toolkit is set up to try and make things easy. If I install the toolkit I can run an app called Docker Quickstart Terminal:

And this will open a terminal where I can use these commands. It will also start the docker machine VM if it has to. It’s even smart enough to recognise if I have multiple terminal apps, such as iTerm, and ask which one I want to use.

This problem is - this doesn’t always work smoothly. Sometimes it will seem that the machine has started but will still not accept commands. Typically a restart is needed in this scenario.

Also, it’s an interruption. If you are running a terminal already and want to issue a quick command, it will fail, unless it was a terminal started with the Docker Quickstart app.

3. inotify - In Container Development

If you recognise the term, you probably know the issue. If not, a little explanation is necessary.

As you get more and more familiar with Docker, you will probably find that you are spending more and more time testing, building then running your image in a container. In fact, you might be changing a single code file and using the container as the dev test server on your machine.

This fast gets painful - the container image takes time to build and slows down the development cycle. There’s a great technique in this scenario: In Container Development.

In container development is pretty much what it sounds like. Instead of editing your code on your machine, building an image and creating a container to debug, you simply create the container with what you need, mount your code in to the container and run all of your development tooling from inside the container:

In this diagram, I have my code locally on my machine. I have built a container which runs nodemon, watching a directory on the container. That directory is actually just a volume containing my code which I have mounted into my container.

This is a really nice technique - I can still code locally, but as I make changes, nodemon serves up my new content.

This specific example applies to Node.js, but can be applied to many scenarios.

The problem is that many watcher tools like nodemon use a kernel subsystem called inotify³ to get notifications when files change. But inotify doesn’t work on virtualbox⁴. This means that this technique isn’t supported for Mac or Windows. There are however some tools which try and work around this with polling.

So now we have another issue. The develop/test process might be nice on Linux, but for devs on other platforms the process is more clunky.

Docker for Mac and Windows to the rescue

The issues I’ve mentioned so far are the big ones which cause me problems personally, I’m sure there are others (please comment and let me know!).

This is why there was rather a lot of interest in the new Docker Beta - one of the big features is that the Docker Machine is going away. In theory, we can use Docker on a Mac or Windows and have the same experience as on Linux.

So how?

Virtualbox is gone. We still need a VM, but this VM is now a very lightweight Alpine Linux based image which runs on xhyve for MacOS and Hyper-V for Windows. All management of this VM is handled by the docker executable.

If these are not familiar terms, Alpine Linux is an extreeeemely lightweight Linux distro originally design to fit on a floppy disk (I think it clocks at around 5 MB now). xhyve is an extremely lightweight hypervisor which allows FreeBSD and some other distros on OSX. Hyper-V is a native hypervisor for Windows Server which can run on Windows 8 onwards⁵.

Using tools specifically designed for each platform (and with the help of both Apple and Microsoft), Docker have been able to make the experience much more seamless and smooth.

Trying It Out

Removing the three pain points discussed and a clean and simple setup process is what I’m looking at today, and here’s the results.

Installation

Piece of cake. Download the beta, install, run, enter the beta key and pop, there’s the new docker:

The new status bar icon gives me a way to quickly see the status of the machine. Some of the commands hint at features to come, others offer the instructions needed. Settings are fairly basic, but I’m not sure what else you’d need:

1. Localhost vs docker-machine IP

Quickly bashing out the commands below shows that the virtual machine IP address issue is gone:

docker run -d -p 3306:3306 -e MYSQL_ROOT_PASSWORD=123 mysql
mysql -uroot -p123 -h127.0.0.1
> show databases;

Great news!

How this works under the hood is a mystery to me. If anyone knows, I’d be interested and would like to update this writeup!

2. Terminal Hassle

Quick and easy to test - running any terminal any way I like lets me access containers using the docker executable - no magic needed:

Here’s a screenshot of iTerm3, the Terminal App and the Terminal App running zsh, all of which are happily communicating with the docker deamon through the docker app.

3. In Container Development

I’ve not thrashed this one too hard, but gone for a quick sanity check. Throwing together probably my best ever node.js app⁶:

main.js

setInterval(function() {
console.log("Goodbye, cruel world!");
}, 1000);

and a simple dockerfile:

Dockerfile

FROM node:6
WORKDIR src/
ADD package.json .
RUN npm install
CMD npm start

is enough to test this. I can build then run the container, mounting the working directory into the src volume on the container:

docker build -t incontainerdev .
docker run -it -v `pwd`:/src incontainerdev]

Immediately, I open a new window and change the source code and save (on my local Mac, not in the container). Voila:

Live reloading works without a hitch! nodemon picks up my changes, using inotify from the VM (all through a lightweight userspace hypervisor).

You know what is cool⁷? I don’t even need Node.js installed to build this Node app! The runtime is in the container, all of the execution happens in the container.

That’s a Wrap

That’s it for my initial impressions. From this point onwards I’m going to be using Docker for Mac heavily as I’ll do all of my work with it installed, so from time to time I may update this article with other observations.

The key takeaway is: at the moment, Docker for Mac just works. I’m using it in the same way I would on Ubuntu with no messing around. This is great, it seems like a simple thing but I’m guessing it was a lot of effort from the guys and girls at Docker, Microsoft and Apple.

This is still a Beta, there’ll be bugs and they’ll be fixed. I can’t wait for the Beta to go fully into the wild, and see what exciting things people can do with it.

As usual, any comments or observations are welcome!

References

Further Reading

Namespaces: http://man7.org/linux/man-pages/man7/namespaces.7.html cgroups: http://man7.org/linux/man-pages/man7/cgroups.7.html Docker Execution Drivers: https://blog.docker.com/2014/03/docker-0-9-introducing-execution-drivers-and-libcontainer/ inotify: http://man7.org/linux/man-pages/man7/inotify.7.html The challenges of in-container development on OSX: http://hharnisc.github.io/2015/09/16/developing-inside-docker-containers-with-osx.html

Read up on namespaces here and cgroups here. Docker can also use LXC but no longer has to, there’s a great write-up here. ↩︎
Surprise! ↩︎
Read up on inotify here ↩︎
The issue will not be resolved: https://www.virtualbox.org/ticket/10660 ↩︎
I’ve not used the Docker for Windows Beta yet so have not got first hand experience of it. I’ve also not looked into compatibility, from memory Hyper-V isn’t available on Home versions of Windows, but I might be wrong. ↩︎
Inspired by my first programming book, the excellent C for Dummies by Dan Gookin. ↩︎
For a given definition of cool. ↩︎

Learn Docker by building a Microservice

Tue, 19 Apr 2016 08:54:39 +0000

If you are looking to get your hands dirty and learn all about Docker, then look no further!

In this article I’m going to show you how Docker works, what all the fuss is about, and how Docker can help with a basic development task - building a microservice.

We’ll use a simple Node.js service with a MySQL backend as an example, going from code running locally to containers running a microservice and database.

Once you’ve read the article, you can find the source code here:

github.com/dwmkerr/node-docker-microservice

What is Docker?

At its heart, Docker is software which lets you create an image (which is a lot like a template for a virtual machine) and then run instances of that image in a container.

Docker maintains a vast repository of images, called the Docker Hub which you can use as starting points or as free storage for your own images. You can install Docker, choose an image you’d like to use, then run an instance of it in a container.

We’re going to build images, create containers from images and more in this article.

Install Docker

To follow along and use this article, you’ll need Docker.

Check the installation guide for your platform, docs.docker.com/engine/installation.

If you are on Mac or Windows, consider using a Virtual Machine. I use Parallels on Mac OS X to run an Ubuntu machine for most development activities. Being able to take snapshots, break things and then revert back is very handy when experimenting.

Try It Out

Enter this command:

docker run -it ubuntu

After a bit of spinning, you’ll see a prompt like this:

root@719059da250d:/#

Try out a few commands and then exit the container:

root@719059da250d:/# lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description: Ubuntu 14.04.4 LTS
Release: 14.04
Codename: trusty
root@719059da250d:/# exit

This doesn’t look like much, but a lot has happened!

What you are seeing is the bash shell of an isolated container running Ubuntu, on your machine. It’s yours to place with - you can install things on it, run software, whatever you want.

Here’s a diagram and breakdown of what just happened (the digram is from the ‘Understanding the Architecture’ Docker Documentation, which is great):

We issue a docker command:

docker: run the docker client
run: the command to run a new container
-it: option to give the container an interactive terminal
ubuntu: the image to base the container on

The docker service running on the host (our machine) checks to see if we have a copy of the requested image locally- which there isn’t.
The docker service checks the public registry (the docker hub) to see if there’s an image named ubuntu available- which there is.
The docker service downloads the image and stores it in its local cache of images (ready for next time).
The docker service creates a new container, based on the ubuntu image.

Try any of these:

docker run -it haskell
docker run -it java
docker run -it python

We’re not going to use Haskell today, but you can see, running an environment is very easy.

It’s a snap to build images of our own, with our apps or services on them, databases, whatever we need. We can then run them on any machine with Docker installed - and the image will run in the same, predictable way. We can build our software and the environment it runs on as code and deploy easily.

Let’s look into a simple microservice as an example.

The Brief

We’re going to build a microservice which lets us manage a directory of email addresses to phone numbers, using Node.js and MySQL.

Getting Started

For doing local development we’ll need to install MySQL and create a test database for us to…

…nope.

Creating a local database and running scripts on it is an easy start, but can get messy. Lots of uncontrolled stuff going on. It might work, we could even control it with some shell scripts checked in to our repo, but what if other developers already have MySQL installed? What if they have a database already with the creative name ‘users’ which we want to create?

Step 1: Creating a Test Database Server - in Docker

This is a great Docker use case. We might not want to run our production database in Docker (perhaps we’ll just use Amazon RDS for example), but we can spin up a clean MySQL database in no time as a Docker container for development - leaving our development machine clean and keeping everything we do controlled and repeatable.

Run the following command:

docker run --name db -d -e MYSQL_ROOT_PASSWORD=123 -p 3306:3306 mysql:latest

This starts a MySQL instance running, allowing access through port 3306 using the root password 123.

docker run tells the engine we want to run an image (the image comes at the end, mysql:vlatest
--name db names this container db.
-d (or --detach) detach - i.e. run the container in the background.
-e MYSQL_ROOT_PASSWORD=123 (or --env) environment variables - tells docker we want to provide an environment variable. The variable following it is what the MySQL image checks for setting the default root password.
-p 3306:3306 (or --publish tells the engine that we want to map the port 3306 from inside the container to out port 3306.

The last part is really important - even though that’s the MySQL default port, if we don’t tell docker explicitly we want to map it, it will block access through that port (because containers are isolated until you tell them you want access).

The return value of this function is the container id, a reference to the container which you can use to stop it, restart it, issue commands on it and so on. Let’s see which containers are running:

$ docker ps
CONTAINER ID IMAGE ... NAMES
36e68b966fd0 mysql:latest ... db

The key information is the container ID, image and name. Let’s connect to this image and see what’s there:

$ docker exec -it db /bin/bash
root@36e68b966fd0:/# mysql -uroot -p123
mysql> show databases;
+--------------------+
| Database |
+--------------------+
| information_schema |
+--------------------+
1 rows in set (0.01 sec)
mysql> exit
Bye
root@36e68b966fd0:/# exit

This is pretty clever too:

docker exec -it db tells docker we want to execute a command on the container named db (we could also use the id, or just the first few letters of the id). -it ensures we have an interactive terminal.
mysql -uroot -p123 the command we actually run as a process in the container, which in this case is just the mysql client.

We can create databases, tables, users, whatever we need.

Wrapping up the Test Database

Running MySQL inside a container has already introduced a few Docker tricks, but let’s pause here and move onto the service. For now, we’ll have create a test-database folder with a script to start the database, stop the database and setup test data:

test-database\setup.sql
test-database\start.sh
test-database\stop.sh

Start is simple:

#!/bin/sh

# Run the MySQL container, with a database named 'users' and credentials
# for a users-service user which can access it.
echo "Starting DB..."
docker run --name db -d \
 -e MYSQL_ROOT_PASSWORD=123 \
 -e MYSQL_DATABASE=users -e MYSQL_USER=users_service -e MYSQL_PASSWORD=123 \
 -p 3306:3306 \
 mysql:latest

# Wait for the database service to start up.
echo "Waiting for DB to start up..."
docker exec db mysqladmin --silent --wait=30 -uusers_service -p123 ping || exit 1

# Run the setup script.
echo "Setting up initial data..."
docker exec -i db mysql -uusers_service -p123 users < setup.sql

This script runs the database image in a detached container (i.e. in the background), with a user set up to access a users database, then waits for the database server to start up, then runs a setup.sql script to set initial data.

setup.sql is:


create table directory (user_id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, email TEXT, phone_number TEXT);
insert into directory (email, phone_number) values ('homer@thesimpsons.com', '+1 888 123 1111');
insert into directory (email, phone_number) values ('marge@thesimpsons.com', '+1 888 123 1112');
insert into directory (email, phone_number) values ('maggie@thesimpsons.com', '+1 888 123 1113');
insert into directory (email, phone_number) values ('lisa@thesimpsons.com', '+1 888 123 1114');
insert into directory (email, phone_number) values ('bart@thesimpsons.com', '+1 888 123 1115');

The stop.sh script will stop the container and remove it (containers are left around by docker by default so that they can be restared quickly, we don’t really need that feature for this example):

#!/bin/sh

# Stop the db and remove the container.
docker stop db && docker rm db

We’re going to make this even more slick later on, simplifying this further. Check the code at this stage by looking at the step1 branch of the repo.

Step 2: Creating a Microservice in Node.js

This article is really focused on learning Docker, so I’m not going to spend ages on the Node.js microservice. Instead, I’ll highlight the areas and takeaways.

test-database/ # contains the code seen in Step 1
users-service/ # root of our node.js microservice
- package.json # dependencies, metadata
- index.js # main entrypoint of the app
- api/ # our apis and api tests
- config/ # config for the app
- repository/ # abstraction over our db
- server/ # server setup code

Let’s take this apart bit by bit. The first section to look at is repository. It can be useful to wrap your database access in some kind of class or abstraction, to allow to mock it for testing purposes:

// repository.js
//
// Exposes a single function - 'connect', which returns
// a connected repository. Call 'disconnect' on this object when you're done.
'use strict';

var mysql = require('mysql');

// Class which holds an open connection to a repository
// and exposes some simple functions for accessing data.
class Repository {
 constructor(connection) {
 this.connection = connection;
 }

 getUsers() {
 return new Promise((resolve, reject) => {

 this.connection.query('SELECT email, phone_number FROM directory', (err, results) => {
 if(err) {
 return reject(new Error("An error occured getting the users: " + err));
 }

 resolve((results || []).map((user) => {
 return {
 email: user.email,
 phone_number: user.phone_number
 };
 }));
 });

 });
 }

 getUserByEmail(email) {

 return new Promise((resolve, reject) => {

 // Fetch the customer.
 this.connection.query('SELECT email, phone_number FROM directory WHERE email = ?', [email], (err, results) => {

 if(err) {
 return reject(new Error("An error occured getting the user: " + err));
 }

 if(results.length === 0) {
 resolve(undefined);
 } else {
 resolve({
 email: results[0].email,
 phone_number: results[0].phone_number
 });
 }

 });

 });
 }

 disconnect() {
 this.connection.end();
 }
}

// One and only exported function, returns a connected repo.
module.exports.connect = (connectionSettings) => {
 return new Promise((resolve, reject) => {
 if(!connectionSettings.host) throw new Error("A host must be specified.");
 if(!connectionSettings.user) throw new Error("A user must be specified.");
 if(!connectionSettings.password) throw new Error("A password must be specified.");
 if(!connectionSettings.port) throw new Error("A port must be specified.");

 resolve(new Repository(mysql.createConnection(connectionSettings)));
 });
};

There’s probably a lot of better ways to do this! But basically we can create a Repository object like this:

repository.connect({
 host: "127.0.0.1",
 database: "users",
 user: "users_service",
 password: "123",
 port: 3306
}).then((repo) => {
 repo.getUsers().then(users) => {
 console.log(users);
 });
 repo.getUserByEmail('homer@thesimpsons.com').then((user) => {
 console.log(user);
 })
 // ...when you are done...
 repo.disconnect();
});

There’s also a set of unit tests in the repository/repository.spec.js file. Now that we’ve got a repo, we can create a server. This is server/server.js:

// server.js

var express = require('express');
var morgan = require('morgan');

module.exports.start = (options) => {

 return new Promise((resolve, reject) => {

 // Make sure we have a repository and port provided.
 if(!options.repository) throw new Error("A server must be started with a connected repository.");
 if(!options.port) throw new Error("A server must be started with a port.");

 // Create the app, add some logging.
 var app = express();
 app.use(morgan('dev'));

 // Add the APIs to the app.
 require('../api/users')(app, options);

 // Start the app, creating a running server which we return.
 var server = app.listen(options.port, () => {
 resolve(server);
 });

 });
};

This module exposes a start function, which we can use like this:

var server = require('./server/server);
server.start({port: 8080, repo: repository}).then((svr) => {
 // we've got a running http server :)
});

Notice that server.js uses api/users/js? Here it is:

// users.js
//
// Defines the users api. Add to a server by calling:
// require('./users')
'use strict';

// Only export - adds the API to the app with the given options.
module.exports = (app, options) => {

 app.get('/users', (req, res, next) => {
 options.repository.getUsers().then((users) => {
 res.status(200).send(users.map((user) => { return {
 email: user.email,
 phoneNumber: user.phone_number
 };
 }));
 })
 .catch(next);
 });

 app.get('/search', (req, res) => {

 // Get the email.
 var email = req.query.email;
 if (!email) {
 throw new Error("When searching for a user, the email must be specified, e.g: '/search?email=homer@thesimpsons.com'.");
 }

 // Get the user from the repo.
 options.repository.getUserByEmail(email).then((user) => {

 if(!user) {
 res.status(404).send('User not found.');
 } else {
 res.status(200).send({
 email: user.email,
 phoneNumber: user.phone_number
 });
 }
 })
 .catch(next);

 });
};

Both of these files have unit tests adjacent to the source.

We’ll need config. Rather than using a specialised library, a simple file will do the trick - config/config.js:

// config.js
//
// Simple application configuration. Extend as needed.
module.exports = {
 port: process.env.PORT || 8123,
 db: {
 host: process.env.DATABASE_HOST || '127.0.0.1',
 database: 'users',
 user: 'users_service',
 password: '123',
 port: 3306
 }
};

We can require config as needed. Currently, most config is hard coded, but as you can see from port it’s easy to add environment variables as an option.

Final step - stringing it together with an index.js file which composes everything:

// index.js
//
// Entrypoint to the application. Opens a repository to the MySQL
// server and starts the server.
var server = require('./server/server');
var repository = require('./repository/repository');
var config = require('./config/config');

// Lots of verbose logging when we're starting up...
console.log("--- Customer Service---");
console.log("Connecting to customer repository...");

// Log unhandled exceptions.
process.on('uncaughtException', function(err) {
 console.error('Unhandled Exception', err);
});
process.on('unhandledRejection', function(err, promise){
 console.error('Unhandled Rejection', err);
});

repository.connect({
 host: config.db.host,
 database: config.db.database,
 user: config.db.user,
 password: config.db.password,
 port: config.db.port
}).then((repo) => {
 console.log("Connected. Starting server...");

 return server.start({
 port: config.port,
 repository: repo
 });

}).then((app) => {
 console.log("Server started successfully, running on port " + config.port + ".");
 app.on('close', () => {
 repository.disconnect();
 });
});

We have a little error handling and beyond that we’re just loading config, creating a repo and starting our server.

That’s the microservice. It allows us to get all users, or search a user:

HTTP GET /users # gets all users
HTTP GET /search?email=homer@thesimpons.com # searches by email

If you checkout the code, you’ll see that there’s a few commands available for you:

cd ./users-service
npm install # setup everything
npm test # unit test - no need for a test database running
npm start # run the server - you must have a test database running
npm run debug # run the server in debug mode, opens a browser with the inspector
npm run lint # check to see if the code is beautiful

Asides from the code you’ve seen we have:

Node Inspector for debugging
Mocha/shoud/supertest for unit tests
ESLint for linting

That’s it!

Run the test database with:

cd test-database/
./start.sh

Then the service with:

cd ../users-service/
npm start

You can point your browser to localhost:8123/users and see it in action. If you are using Docker Machine (i.e. you’re on Mac or Windows) then localhost won’t work, you need the IP of the docker machine instead. You can use docker-machine ip to get it.

We’ve whipped through building the service quickly. If you’d like to see this code before we continue, check the step2 branch.

Step 3: Dockerising our Microservice

OK now it gets fun!

So we have a microservice which we can run on a dev box, as long as it has a compatible version of Node.js installed. What we’d like to do is set up our service so that we can create a Docker Image from it, allowing us to deploy our service anywhere which supports docker.

The way we do this is create a Dockerfile. A Dockerfile is a recipe that tells the Docker engine how to build your image. We’ll create a simple Dockerfile in our users-service directory and start to explore how we can adapt it to our needs.

Creating the Dockerfile

Create a new text file called Dockerfile at users-service/ with the content below:

# Use Node v4 as the base image.
FROM node:4
# Run node
CMD ["node"]

Now run the commands below to build the image and run the a container from it:

docker build -t node4 . # Builds a new image
docker run -it node4 # Run a container with this image, interactive

Let’s look at the build command first.

docker build tell the engine we want to create a new image.
-t node4 tag this image with the tag node4. We can refer to this image by tag from now on.
. use the current directory to find the Dockerfile.

After some console output you’ll see we have a new image created. You can see all images on your system with docker images. The next command should be fairly familiar from what we’ve done so far:

docker run run a new container from an image.
-it use an interactive terminal.
node4 the tag of the image we want to use in the container.

When we run this image, we get a node repl, check the current version like so:

> process.version
'v4.4.0'
> process.exit(0)

This is potentially different to the node version on your current machine.

Examining the Dockerfile

Looking at the dockerfile we can see quite easily what is going on:

FROM node:4 the first thing we specify in a Dockerfile is the base image. A quick google finds the node organisation page on the docker hub showing all of the available images. This is essentially bare bones ubuntu with node installed.
CMD ["node"] the CMD command tells docker that this image should run the node executable. When the executable terminates, the container shuts down.

With the addition of a few more commands, we can update our Dockerfile so that it runs our service:

# Use Node v4 as the base image.
FROM node:4
# Add everything in the current directory to our image, in the 'app' folder.
ADD . /app
# Install dependencies
RUN cd /app; \
npm install --production
# Expose our server port.
EXPOSE 8123
# Run our app.
CMD ["node", "/app/index.js"]

The only addition here is that we use the ADD command to copy everything¹ in the current directory to a folder in the container called app/ . We then use RUN to run a command in the image, which installs our modules. Finally, we EXPOSE the server port, telling docker we intend to support inbound connections on 8123, then run our server code.

Ensure the test-database service is running, then build and run the image again:

docker build -t users-service .
docker run -it -p 8123:8123 users-service

If you navigate to localhost:8123/users in a browser you should see an error, checking the console shows our container is reporting some issues:

--- Customer Service---
Connecting to customer repository...
Connected. Starting server...
Server started successfully, running on port 8123.
GET /users 500 23.958 ms - 582
Error: An error occured getting the users: Error: connect ECONNREFUSED 127.0.0.1:3306
at Query._callback (/app/repository/repository.js:21:25)
at Query.Sequence.end (/app/node_modules/mysql/lib/protocol/sequences/Sequence.js:96:24)
at /app/node_modules/mysql/lib/protocol/Protocol.js:399:18
at Array.forEach (native)
at /app/node_modules/mysql/lib/protocol/Protocol.js:398:13
at nextTickCallbackWith0Args (node.js:420:9)
at process._tickCallback (node.js:349:13)

Yikes! So the connection from our users-service container to the test-database container is being refused. We might try running docker ps to see all containers running:

CONTAINER ID IMAGE PORTS NAMES
a97958850c66 users-service 0.0.0.0:8123->8123/tcp kickass_perlman
47f91343db01 mysql:latest 0.0.0.0:3306->3306/tcp db

They’re both there, so what is going on?

Linking Containers

The issue we’ve seen is actually to be expected. Docker containers are supposed to be isolated, so it wouldn’t make much sense if we could create connections between containers without us explicitly allowing it.

Yes, we can connect from our machine (the host) to a container, because we’ve opened ports for that (using the -p 8123:8123 argument for example). If we allowed containers to talk to each other in the same way, then two containers running on the same machine would be able to communicate, even if the developers didn’t intend it, and that’s a recipe for disaster, especially when we might have a cluster of machines whos job it is to run containers from different applications.

If we’re going to connect from one container to another, we need to link them, which tells docker that we explicitly want to allow communication between the two. There are two ways of doing this, the first is the ‘old fasioned’ but quite simple way, the second we’ll see a little later.

Linking Containers with the ’link’ parameter

When we run a container, we can tell docker that we intend to connect to another container using the link parameter. In our case, we can run our service correctly like this:

docker run -it -p 8123:8123 --link db:db -e DATABASE_HOST=DB users-service

docker run -it run a docker image in a container, with an interactive terminal.
-p 8123:8123 map the host port 8123 to the container port 8123.
link db:db link to the container named db and refer to it as db.
-e DATABASE_HOST=db set the DATABASE_HOST environment variable to db.
users-service the name of the image to run in our container.

Now when we go to localhost:8123/users everything works.

How it works

Remember our config file for the service? It allowed us to specify a database host with an environment variable:

// config.js
//
// Simple application configuration. Extend as needed.
module.exports = {
 port: process.env.PORT || 8123,
 db: {
 host: process.env.DATABASE_HOST || '127.0.0.1',
 database: 'users',
 user: 'users_service',
 password: '123',
 port: 3306
 }
};

When we run the container, we set this environment variable to DB, which means we’re connecting to a host called DB. This is automatically set up for us by the docker engine when we link to a container.

To see this in action, try running docker ps to list all running containers. Look up the name of the container running the users-service, which will be a random name such as trusting_jang:

docker ps
CONTAINER ID IMAGE ... NAMES
ac9449d3d552 users-service ... trusting_jang
47f91343db01 mysql:latest ... db

Now we can look at the hosts available on our container:

docker exec trusting_jang cat /etc/hosts
127.0.0.1 localhost
::1 localhost ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters
172.17.0.2 db 47f91343db01 # linking magic!!
172.17.0.3 ac9449d3d552

Remember how docker exec works? Choose a container name and then whatever follows is the command you’ll execute on the container, in our case cat /etc/hosts.

OK the hosts file doesn’t have the # linking magic!! comment, that’s so you can see - docker has added db to our hosts file so we can refer to the linked container by hostname. This is one consequence of linking. Here’s the other:

docker exec trusting_jang printenv | grep DB
DB_PORT=tcp://172.17.0.2:3306
DB_PORT_3306_TCP=tcp://172.17.0.2:3306
DB_PORT_3306_TCP_ADDR=172.17.0.2
DB_PORT_3306_TCP_PORT=3306
DB_PORT_3306_TCP_PROTO=tcp
DB_NAME=/trusting_jang/db

From this command we can also see that when docker links a container, it also provides a set of environment variables with some helpful information. We know the host, tcp port and container name.

That’s step 3 complete - we have a MySQL database running happily in a container, we have a node.js microservice which we can run locally or in a container of its own, and we know how to link them together.

You can check out how the code looks at this stage by going to the step3 branch.

Step 4: Integration Testing the Environment

We can now write an integration test which calls the actual server, running as a docker container, calling the containerised test database.

Writing the integration test can be done in whatever language or on whatever platform you want, within reason, but to keep things simple I’m using Node.js as we’ve already seen Mocha and Supertest in our project.

In a new folder, called integration-tests we’ve got a single index.js:

var supertest = require('supertest');
var should = require('should');

describe('users-service', () => {

 var api = supertest('http://localhost:8123');

 it('returns a 200 for a known user', (done) => {

 api.get('/search?email=homer@thesimpsons.com')
 .expect(200, done);
 });

});

This will check an API call and show the results of the test².

As long as your users-service and test-database are running, the tests will pass. However, at this stage the services are getting a little harder to handle:

We have to use a shell script to start and stop the database
We have to remember a sequence of commands to start the users service against the database
We have to use node directly to run the integration tests

Now that we’re a little more familiar with Docker we can fix these issues.

Simplifiying the Test Database

Currently we have the following files for the test database:

/test-database/start.sh
/test-database/stop.sh
/test-database/setup.sql

Now that we’re more familar with Docker, we can improve on this. Looking into the mysql image documentation on Docker Hub there’s a note which tells us any .sql or .sh file added to the image’s /docker-entrypoint-initdb.d folder will be executed when setting up the DB.

This means we can replace our start.sh and stop.sh scripts with a Dockerfile:

FROM mysql:5
ENV MYSQL_ROOT_PASSWORD 123
ENV MYSQL_DATABASE users
ENV MYSQL_USER users_service
ENV MYSQL_PASSWORD 123
ADD setup.sql /docker-entrypoint-initdb.d

Now to run our test database it is just:

docker build -t test-database .
docker run --name db test-database

Composing

Building and running each container is still somewhat time consuming. We can take things a step further with the Docker Compose tool.

Docker Compose lets you create a file which defines each container in your system, the relationships between them, and build or run them all.

First, install Docker Compose. Now create a new file in the root of your project called docker-compose.yml:

version: '2'
services:
users-service:
build: ./users-service
ports:
- "8123:8123"
depends_on:
- db
environment:
- DATABASE_HOST=db
db:
build: ./test-database

Now check this out:

docker-compose build
docker-compose up

Docker Compose has built all of the images needed for our application, created containers fromthem, run them in the correct order and started the whole stack!

The docker-compose build command builds each image which is listed in the docker-compose.yml file:

version: '2'
services:
users-service:
build: ./users-service
ports:
- "8123:8123"
depends_on:
- db
environment:
- DATABASE_HOST=db
db:
build: ./test-database

The build value for each of our services tells docker where to go to find the Dockerfile. When we run docker-compose up, docker starts all of our services. Notice from the Dockerfile we can specify ports and dependencies. Actually, there’s a whole bunch of config we can change here.

In another terminal, run docker compose down to gracefully shut down the containers.

Winding Up

We’ve seen a lot of docker in this article, but there’s a lot more to it. I hope this has shown some of the interesting and useful things that you can use docker for in your workflow.

As usual, questions and comments are welcomed! I’d also strongly recommend the document Understanding Docker to get a deeper understanding of how docker works.

You can see the final source code for the project built in this article at github.com/dwmkerr/node-docker-microservice

Notes

Copying everything is actually a bad idea, because we will also copy the node_modules folder. Generally it is a better idea explicitly list the files or folders you want to copy, or use a .dockerignore file, which works just like the .gitignore file. ↩︎
If the server isn’t running, it will actually show a rather annoying exception, due to a bug in supertest, see github.com/visionmedia/supertest/issues/314. ↩︎

Manipulating JSON Web Tokens (JWTs)

Tue, 24 Mar 2015 14:45:02 +0000

I’ve been writing a couple of web services lately that use Auth0 for identity management. It’s a great platform that makes working with different identity providers a breeze.

One thing that I couldn’t work out how to do at first was to quickly build a new JWT¹ from an existing token. I wanted to take my current token, add some more data to it and return it to the user. So here’s a ‘why’ and ‘how’.

Why?

Why would you want to do this? A use case would be when you want to associate your a session with some data. For example, imagine a library gateway which offers access to a whole bunch of University libraries. First we authenticate. Then we ask for all of the libraries in the system. Then we ask for authorisation to use a specific library. We could put the library name in the token and pass it for every call onwards.

It might look like this:

1. Authenticate

First, we authenticate, perhaps with a username and password.

POST libraries.com/api/authenticate
{"usename":"calculon","password":"dramatic...pause"}

Then we can return a JWT if all is well:

{"jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjYWxjdWxvbiJ9.VWkAafAMCxazY7uBlPTJoQwCBdUIy3T1d-C4TfxhAZQ"}

2. Work with the Service

We can put this JWT in an Authorization header and start asking for protected resources:

GET libraries.com/api/libraries
Authorization: Bearer eyJhb...AZQ

giving us:

[
{"name": "Mars University Libary", "slug":"mul"},
{"name": "Coney Island State Library", "slug":"cis"}
]

Two libraries we can choose from. Now I want to present this choice to a user, but once they’ve made their choice I don’t want to change the libary again. I want to work with only one library in a session.

3. Add Data to the Token

A nice thing we can do here is just create another authentication method, which attempts to see if we are authorised to use the given library:

POST libraries.com/api/libraries/mul/authorise
Authorization: Bearer eyJhb...AZQ

If the token is valid, we can check to see if the user is allowed to use this library. If so, we can return a new token, which is associated with a specific library:

HTTP/1.1 200 OK
{"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjYWxjdWxvbiIsImxpYnJhcnkiOiJtdWwifQ.NM2pqRMkIp65u9unZnGIoyxK6v2A18730lPwSMrK93Q"}

This is a new token. Paste it into jwt.io, you’ll see there’s a library code in the payload.

4. Work with the service

Now I can call APIs like:

GET libaries.com/api/books

And my server can check the library in my token. If I have one, I return books from the given library, otherwise I return a 401.

Is this useful?

This specific example might not appeal, but you may well find as you write more complex services you want to at times add data to your token.

The case above also shows how you can associate a session with a set of resources (in this case, a single library). This is useful if we know we’ll only work with a subset of resources. I want to choose a library once and work with that only. If you need to work with multiple libraries, it wouldn’t make sense.

How?

If we are using Auth0, then we almost certainly have our token generated for us. The helper library express-jwt will certainly let us make sure the token is valid, and put the payload of data on the request.user object, but how can we create a new token from the existing one?

It turns out it’s really pretty easy, as we would expect as we are using open standards. Here’s the code:

var jwt = require('jsonwebtoken');

function extendToken(secret, payload, extend) {

 // Clone and extend the payload.
 var body = JSON.parse(JSON.stringify(payload));
 for (var prop in extend) {
 if (extend.hasOwnProperty(prop)) {
 body[prop] = extend[prop];
 }
 }

 // Sign the new token with our secret.
 return jwt.sign(JSON.stringify(body), secret);

}

We have a function which takes a secret, the payload of an existing token, an object containing data to extend and that’s it. Here’s how you could use it:

var expressJwt = require('express-jwt');
var mySecret = new Buffer('walkinonsunshine', 'base64');

// Middleware for protecting routes...
var requireAuth = expressJwt({secret: mySecret});

app.post('/api/libraries/:lib/authorise', requireAuth, function(req, res, next) {

 // get the library, check the user has access...
 var lib = req.params.lib;
 checkLib(req.user.sub, lib, function(err, ok) {

 if(err) return next(err);
 if(!ok) return res.status(401).send("Access Denied.");
 return res.status(200).send({jwt: extendToken(mySecret, req.user, {library: lib})});

 });

});

We’ve extended the original token with some new data, resigned it and passed it back to the user. Future requests will automatically have the req.user.lib field set (as the entire token payload is put by default on the req.user object with the express-js middleware.

Hopefully that’ll be of some use if you ever need to extend the payload of a JWT token in a Node app.

^{1. Json Web Token, read more at jwt.io. ↩}

Blogging with Ghost

Mon, 05 May 2014 04:35:09 +0000

tl;dr Ghost is a blogging platform well worth considering if your blog is all about development.

I’ve been having some gripes with WordPress as a platform for blogging lately. For development focused blogs like this one, there are some things about it that make writing posts just a little bit clunky. For example:

Syntax Higlightling is always going to use plugins with various shortcode formats. This works, but your raw blog text becomes quite specific to a certain implementation.
It’s kind of slow, unless you use a theme that’s loading as much content as possible with Ajax.
There aren’t a great number of simple, content focused themes that appeal to dev type blogs.

The final point - I want to blog in Markdown its a simple syntax that doesn’t require a fancy editor and I use it every day for work.

Enter Ghost

A little bit of research led me to Ghost. It’s a fairly new, simple blogging platform with few features, but the features it has it does well. You write your posts in Markdown. If you need fancy syntax highlighting, you can have it, over and above that there’s not much to it.

Ghost runs on Node.js, so it’s simple to install. The data is stored in SqlLite and the blog is ajaxy - without many full page loads.

There are no comments, but you can easily integrate Disqus into your blog if you feel you need them.

I’m hosting my old WordPress blog at oldblog.dwmkerr.com and currently migrating things over.

Installing on IIS

This server is actually running IIS, unlike my droplets on Digital Ocean. If you’re installing Ghost on IIS, I strongly recommend How to set up Node.js, iisnode and Ghost on IIS - it was this post that had the clearest and most up to date instructions.

Final Thoughts

Before you consider the leap, be aware that Ghost is quite new - features are changing or being added, and if you need lots of complicated stuff you might not find it up to the job. However there’s already an active community and it looks like its only getting better.

If it’s markdown you want - you can use it in WordPress, just find the right plugin and you’re done.

Node.js and Express - Strange Http Status Codes

Tue, 16 Jul 2013 16:23:43 +0000

In a Nutshell

Sending a response in Express with a call like res.send(status, body) will send body as the status code if it is numeric - ignoring status. This is due to a fudge for backwards compatibility.

The Details

As part of a project I'm working on, I'm writing a service using node.js and Express. This service exposes some entities in a MongoDB database through a REST API. Typically I hit this API through client-side Javascript, but in some places I want to hit the same API from some C# code - and I don't want to have to create classes for everything. I've got a funky library for this which I'll be publishing soon, but it helped me find a problem.

Testing the C# code showed me something that was a bit odd - GETs and POSTSs were working fine, but PUTs and DELETEs were showing an HTTP Status code of ‘1’ (which isn’t a valid code). Here’s the what I was seeing:

Checking the node server showed the same thing - DELETEs were returning status 1.

The server code is very lightweight so it’s quick to see what’s going on:

[code lang=“js”]exports.deleteUser = function(request, response) {

// Get the id.
var id = request.params.id;
// Log the user id.
console.log('Deleting user: ' + id);
// Get the users collection, delete the object.
db.collection(collectionName, function(err, collection) {
collection.remove({'_id':new BSON.ObjectID(id)}, {safe:true}, function(err, result) {
if (err) {
console.log('Error deleting user: ' + err);
response.send(400, {'error':'An error has occurred'});
} else {
console.log('' + result + ' document(s) deleted');
response.send(result);
}
});
});

}[/code]

The function is called successfully, so we hit ‘response.send’. This looks like the problem - the result object is simply the number one, checking the Express Api Documentation for send shows some examples like this:

res.send(new Buffer('whoop'));
res.send({ some: 'json' });
res.send('some html');
res.send(404, 'Sorry, we cannot find that!');
res.send(500, { error: 'something blew up' });
res.send(200);

So just like the final example, we’re sending the code 1, which is not valid. What surprised me was what happened when I changed the send call to the below:

[code lang=“js”]response.send(200, result)[/code]

I was still getting the code 1 returned. It turns out that this is a kind of undocumented oddity of Express - if you pass a numeric code and the second argument is also numeric it sends the second argument as the status.

In response.js of Express we find:

[code lang=“js”]res.send = function(body){ var req = this.req; var head = ‘HEAD’ == req.method; var len;

// allow status / body if (2 == arguments.length) { // res.send(body, status) backwards compat if (’number’ != typeof body && ’number’ == typeof arguments[1]) { this.statusCode = arguments[1]; } else { this.statusCode = body; body = arguments[1]; } }[/code]

So it seems the Express used to support a call like res.send({body}, 200) - and checks for a numeric second argument for backwards compatibility.

The workaround - don’t send numbers as any part of the response, unless it’s most definitely the status code - if you want to return the number of documents deleted, format it as json first, otherwise Express will get confused and mess with your status codes.