Tuesday, March 8, 2011

Getting Started with Node.js

Node.js is a server-side, event-driven environment that I am using to wrap my code generation scripts up and present them as a service.  I wanted a HTTP service that was simple and quick without much ‘fluff’. Node.js definitely comes without ‘fluff.  In this post I’m going to give you a quick overview of Node. It is not a deep dive but a quick example of ‘normal’ web requests.

The Setup

One thing I need to point out that Node.js is primarily a linux/unix/bsd solution. Supposedly you can run it on windows but it is not recommended. In my development environment I am running it on a Ubuntu 10.04 VM. I installed node and its package management system (npm) by following these instructions. Since the instructions are clear I won’t duplicate them here. After node is installed it is time for a quick test.

Hello World Node.js Style

Actually I didn’t write my own ‘Hello World’ I just copied the one from the node.js home page. Here’s what it looks like:

The code is pretty straight forward. The first line creates a the http object that we’ll use to create our HTTP server. Next, the script creates a web server object that takes in a function that is added to the request event queue. In the body of the function the first line creates the response’s header. The second line sends our Hello, World statement back to the browser. Lastly, the http server object’s listen method is called to tell the server to listen on the port 8124 on the local address.
To start the server I simply type:
node hello-world.js
Once the server has started the console.log message is printed which shows that the service is open for business. The hello world script works but it will send the hello world message to any GET request it receives on the port, http://localhost:8124 , http://localhost:8124/rob/was/here, etc all return the same message. You can set up 'straight' node.js to respond to different urls but I found an easier way to do it using express.js

Introducing Express.js

Express.js is a package that will turn our node.js script into something that looks like the JavaScript version of Sinatra. Before I show you what the code looks you need to install express.js.

Installation

If you followed the instructions for installing node.js to the letter you’ve already installed the package manager (npm). If you skipped the npm install earlier, install npm now. To install express simple run this from the command line:
npm install express
That’s it. Now we can use it to help us build out our service.

Hello World – Express.js version

Here’s our hello world service with express:

The first line is similar to the pure node.js one except that I create the app object after ‘requiring’ the library. The next line is where the express.js goodness kicks in. The line is is telling the server that whenever you receive an HTTP GET request for the url ‘/’ run the function that is passed into the app.get method call. Now, If start the service and run:
curl http://localhost:8124
I will see 'Hello World' written to STDOUT. If I tack on /Rob to the end of the URL I will receive an error that states:
Cannot GET /Rob

Retrieving Parameters (GET version)

So what if I want to pass the string Rob in as a parameter, how would I do that with express.js? It is pretty easy. Here is an updated version of the code that supports passing in a name as a parameter.

As you can see there isn’t much to adding parameters. A few things I’d like to point out are that the ? after the parameter name means that the parameter is not required. If one is passed it will be used. If no value is passed in we will still respond to the / request. Parameters are accessed by making referencing:
req.params.<variable name here>
That’s great but how do I do POST requests with express.js?

Retrieving Parameters (POST version)

How do you respond to a POST request? I’m sure you’ve probably already figured that out but I’ll show you the code to handle a post:

The app.post method is almost the same as the app.get method. If you look at the parameters to the fs.writeFile method you will notice the one visible difference in this code snippet, the parameters are accessed via the req.body object. I’m going to start the service and then call it with the following command:
curl -d "path=/tmp/blog.txt&content=Hi, Rob\n" http://localhost:8124/savefile
When I run that I get the following error:

Why did I receive this error? Out of the box Express.js doesn’t know how to parse the variables from a POST. In order to access the POST variables with express we need to add a piece of middle ware one line to our script:
app.use(express.bodyDecoder());
app.use(express.bodyParser());
Updated after updated Express.js - Thanks Douglas

Now express.js will be able to parse the parameters and store them in the req.body object. If I re-start the service and run the curl statement I should see the statement ‘File Saved!’ and have a text file at /tmp/blog.txt with the content ‘Hi, Rob’. Handling POST requests are almost as easy as handling GETs.
The full hello-world-express.js script:

Summary

This only scratches the surface as far as node.js goes. There are all kinds of packages available for node ones like express, view engines, low-level functionality, etc. In my project I’m using node.js as a middle man that has access to Riak, via raik-js), run my code generation scripts, and manage the code that is generated be the scripts. Due to Node's simplicity, I have been able to concentrate on the functionality that I’m trying to implement and not messing with server configurations.

3 comments:

  1. Great post!

    One note: express.bodyDecoder() is now express.bodyParser()

    ReplyDelete
  2. Thank you Douglas. I just updated express and I see that. I'll updated the blog shortly.

    ReplyDelete