Node

Purely asynchronous I/O for V8 javascript.

This is an example of a web server written with Node which responds with "Hello World" after waiting two seconds:

new node.http.Server(function (req, res) {
  setTimeout(function () {
    res.sendHeader(200, [["Content-Type", "text/plain"]]);
    res.sendBody("Hello World");
    res.finish();
  }, 2000);
}).listen(8000);
puts("Server running at http://127.0.0.1:8000/");

Execution does not block on setTimeout() nor listen(8000). In fact, not a single function in Node blocks execution.

Programming in Node is different. Instead of commanding actions, Node scripts defining behaviors. The entire program is centered around I/O events.

Check out the API documentation for more examples.

Node is free to download, use, and build upon.

Motivation

I/O is hard and almost no one gets it right. This is an attempt to make you to do it right by taking away all those sharp, dangerous tools called threads.

Node is forced evented programming—so by default you are doing the right thing. Well, actually, Javascript itself is forced evented programming. Node brings Javascript, in the way it was meant to be, out of the browser.

There is a major difference in the latency between memory and disk I/O. It looks approximately like this:

l1 cache ~ 3          (CPU cycles)
l2 cache ~ 14
     ram ~ 250
    disk ~ 41000000
 network ~ 240000000

Disk and network I/O need to be treated differently than simple memory operations. But POSIX obscures the latency with system calls like

close(file_descriptor);

For a TCP file descriptor, this is a round trip message to a remote computer that can cost billions of CPU cycles. For a hard drive file descriptor, close() could mean a couple million cycles of disk spinning. The man pages don't even mention that a call might be preforming very long I/O operations. This ambiguity in POSIX is propagated into higher APIs.

In the Node API all I/O happens on the event loop and thus requires a callback of some sort. Calls to access foreign database do not look like simple side-effect free functions. The programmer does not need advanced knowledge of POSIX to know that I/O is being performed because it looks differently.

Some find event programming cumbersome. I find threaded programming cumbersome—it's not a good abstraction of what is really happening. Because of this bad abstraction it's confusing and difficult to get right. Threaded programs only look good in the simpliest and most trivial situations—in real-life applications events lead to better architecture.

Benchmarks

TODO

Download

TODO

Build

./configure
make
make install

Application Programming Interface

Conventions: Callbacks are object members which are prefixed with on. All methods and members are camel cased. Constructors always have a capital first letter.

Timers

Timers allow one to schedule execution of a function for a later time.

Timers in Node work as they do in the browser: setTimeout, setInterval, clearTimeout, clearInterval. See Mozilla's documentation for more information.

File System

`node.tcp`

`node.http`

Node provides a web server and client interface. The interface is rather low-level but complete. For example, it does not parse application/x-www-form-urlencoded message bodies. The interface does abstract the Transfer-Encoding (i.e. chuncked or identity), Message boundaries, and Keep-Alive connections.

`node.http.Server`

var server = new node.http.Server(request_handler, options);

Creates a new web server.

The options argument is optional. The options argument accepts the same values as the options argument for node.tcp.Server does.

The request_handler is a callback which is made on each request with a ServerRequest and ServerResponse arguments.

server.listen(port, hostname)

Begin accepting connections on the specified port and hostname. If the hostname is omitted, the server will accept connections directed to any address.

server.close()

Stops the server. Requests currently in progress will not be interrupted.

`node.http.ServerRequest`

This object is created internally by a HTTP server—not by the user. It is passed as the first argument to the request_handler callback.

req.method

The request method as a string. Read only. Example: "GET", "DELETE".

req.uri

URI object. Has many fields.

req.uri.toString()

The original URI found in the status line.

req.uri.anchor

req.uri.query

req.uri.file

req.uri.directory

req.uri.path

req.uri.relative

req.uri.port

req.uri.host

req.uri.password

req.uri.user

req.uri.authority

req.uri.protocol

req.uri.source

req.uri.queryKey

req.headers

The request headers expressed as an array of 2-element arrays. Read only. Example:

[ ["Content-Length", "123"]
, ["Content-Type", "text/plain"]
, ["Connection", "keep-alive"]
, ["Accept", "*/*"]
]

req.http_version

The HTTP protocol version as a string. Read only. Examples: "1.1", "1.0"

req.onBody

Callback. Should be set by the user to be informed of when a piece of the message body is received. Example:

req.onBody = function (chunk) {
  puts("part of the body: " + chunk);
};

A chunk of the body is given as the single argument. The transfer-encoding has been removed.

The body chunk is either a String in the case of UTF-8 encoding or an array of numbers in the case of raw encoding. The body encoding is set with req.setBodyEncoding().

req.onBodyComplete

Callback. Made exactly once for each message. No arguments. After onBodyComplete is executed onBody will no longer be called.

req.setBodyEncoding(encoding)

Set the encoding for the request body. Either "utf8" or "raw". Defaults to raw. TODO

`node.http.ServerResponse`

res.sendHeader(status_code, headers)

Sends a response header to the request. The status code is a 3-digit HTTP status code, like 404. The second argument, headers, should be an array of 2-element arrays, representing the response headers.

Example:

var body = "hello world";
res.sendHeader(200, [ ["Content-Length", body.length]
                    , ["Content-Type", "text/plain"]
                    ]);

This method must only be called once on a message and it must be called before res.finish() is called.

res.sendBody(chunk)

This method must be called after sendHeader was called. It sends a chunk of the response body. This method may be called multiple times to provide successive parts of the body.

res.finish()

This method signals that all of the response headers and body has been sent; that server should consider this message complete. The method, res.finish(), MUST be called on each response.

Modules

Node has a simple module loading system. In Node, files and modules are in one-to-one correspondence.

As an example, foo.js loads the module mjsunit.js.

The contents of foo.js:

include("mjsunit");
function onLoad () {
  assertEquals(1, 2);
}

The contents of mjsunit.js:

function fail (expected, found, name_opt) {
  // ...
}
function deepEquals (a, b) {
  // ...
}
exports.assertEquals = function (expected, found, name_opt) {
  if (!deepEquals(found, expected)) {
    fail(expected, found, name_opt);
  }
};

Here the module mjsunit.js has exported the function assertEquals(). mjsunit.js must be in the same directory as foo.js for include() to find it. The module path is relative to the file calling include(). The module path does not include filename extensions like .js.

include() inserts the exported objects from the specified module into the global namespace.

Because file loading does not happen instantaneously, and because Node has a policy of never blocking, the callback onLoad can be set and will notify the user when all the included modules are loaded. Each file/module can have an onLoad callback.

To export an object, add to the special exports object.

The functions fail and deepEquals are not exported and remain private to the module.

require() is like include() except does not polute the global namespace. It returns a namespace object. The exported objects can only be guaranteed to exist after the onLoad() callback is made. For example:

var mjsunit = require("mjsunit");
function onLoad () {
  mjsunit.assertEquals(1, 2);
}

include() and require() cannot be used after onLoad() is called. So put them at the beginning of your file.