nodejs/website/node.html


<html>
<style>
body {
  background: #22252a;
  color: #eee;
  font-size: 16pt;
  line-height: 150%;
  font-family: times, Times New Roman, times-roman, georgia, serif; 
}
#content {
  max-width: 30em;
  margin: 0 0 5em 10em;
}
#toc {
  position: fixed;
  top: 2em;
  left: 0;
  width: 10em;
}
#toc ol {
  list-style: none;
  margin: 0;
  padding: 0;
  padding-left: 1em;
}
#toc ol li {
  margin: 0;
  padding: 0;
}
#toc a { color: #777; }

h1, h2, h3, h4 {
  color: #B0C4DE;
  margin: 2em 0; 
}

h1 a { color: inherit; }


pre, code {
  font-family: monospace;
  font-size: 14pt;
  color: #dcd;
}

pre {
  padding-left: 1em;
  border-left: 1px solid #444;
}

dl {
}

dt {
}

dd {
  margin: 1em 0;
  margin-left: 1em;
}

a { color: #cd5; text-decoration: none; }
a:hover { text-decoration: underline; }

.highlight {
  background: #733;
  padding: 0.2em 0;
}

</style> 
<script type="text/javascript" src="sh_main.js"></script>
<script type="text/javascript" src="sh_javascript.min.js"></script>
<link type="text/css" rel="stylesheet" href="sh_vim-dark.css">

<title>node.js</title>
<body onload="sh_highlightDocument();">
<div id="toc">
  <ol>
    <li><a href="#motivation">Motivation</a></li>
    <li><a href="#benchmarks">Benchmarks</a></li>
    <li><a href="#download">Download</a></li>
    <li><a href="#install">Build</a></li>
    <li><a href="#api">API</a>
      <ol>
        <li><a href="#timers">Timers</a>
        <li><a href="#files">File System I/O</a>
        <li><a href="#tcp">TCP</a>
        <li><a href="#http">HTTP</a>
          <ol>
          <li><a href="#http_server">Server</a>
          <li><a href="#http_server_request">ServerRequest</a>
          <li><a href="#http_server_response">ServerResponse</a>
          <li><a href="#http_client">Client</a>
          </ol>
        <li><a href="#modules">Modules</a>
      </ol>
    </li>
  </ol>
</div>
<div id="content">

<h1><a href="http://tinyclouds.org/node">Node</a></h1>

<p id="introduction"> Purely asynchronous I/O for <a
  href="http://code.google.com/p/v8/">V8 javascript</a>. 
  
<p>This is an example of a web server written with Node which responds with
"Hello World" after waiting two seconds:

<pre class="sh_javascript">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/");</pre>

<p> Execution does not block on <code
class="sh_javascript">setTimeout()</code>
nor
<code
class="sh_javascript">listen(8000)</code>. 
In fact, not a single function in Node blocks execution. 

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

<p> Check out <a href="#api">the API documentation</a> for more examples.

<p> Node is free to <a href="#download">download</a>, <a
  href="#api">use</a>, and <a href="#modules">build upon</a>.</p>


<h2 id="motivation">Motivation</h2>

<p>
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 <i>threads</i>.

<p>
Node is forced evented programming&mdash;so by default you are doing the
right thing.  
Well, actually, <a
href="http://weblogs.mozillazine.org/roadmap/archives/2007/02/threads_suck.html">Javascript
itself is forced evented programming</a>. Node brings Javascript, in the way
it was meant to be, out of the browser.

<p>
<a
href="http://duartes.org/gustavo/blog/post/what-your-computer-does-while-you-wait">There
is a major difference in the latency between memory and disk I/O.</a> It looks
approximately like this:

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

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

<pre>close(file_descriptor);</pre>

<p> 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,
<code>close()</code> 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.

<p> 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.

<p> Some find event programming cumbersome.
I find threaded programming
cumbersome&mdash;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&mdash;in real-life applications events lead to better
architecture.


<h2 id="benchmarks">Benchmarks</h2>

<p> TODO

<h2 id="download">Download</h2>

<p> TODO

<h2 id="build">Build</h2>

<pre>./configure
make
make install</pre>


<h2 id="api">Application Programming Interface</h2>

<p>Conventions: Callbacks are object members which are prefixed with
<code class="sh_javascript">on</code>. All methods and members are camel cased. Constructors
always have a capital first letter.

<h3 id="timers">Timers</h3>

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

<p>Timers in Node work as they do in the browser: 
<code class="sh_javascript">setTimeout</code>, 
<code class="sh_javascript">setInterval</code>, 
<code class="sh_javascript">clearTimeout</code>, 
<code class="sh_javascript">clearInterval</code>.
See <a
  href="https://developer.mozilla.org/en/DOM/window.setTimeout">Mozilla's
  documentation</a> for more information.

<h3 id="files">File System</h3>

<h3 id="tcp"><code>node.tcp</code></h3>

<h3 id="http"><code>node.http</code></h3>

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

<h4 id="http_server"><code class="sh_javascript">node.http.Server</code></h4>

<dl>
  <dt><code class="sh_javascript">var server = new node.http.Server(request_handler, options);</code></dt>
  <dd> 
      <p>Creates a new web server. 

      <p>
      The <code>options</code> argument is optional. 
      The <code
      class="sh_javascript">options</code> argument accepts the same values
      as the options argument for <code
      class="sh_javascript">node.tcp.Server</code> does.

      <p>The <code class="sh_javascript">request_handler</code> is a
      callback which is made on each request with a 
      <code>ServerRequest</code> and 
      <code>ServerResponse</code> arguments.  

  </dd>

  <dt><code class="sh_javascript">server.listen(port, hostname)</code>
  <dd> 
    <p>Begin accepting connections on the specified port and hostname. If the
    hostname is omitted, the server will accept connections directed to any
    address.  
  </dd>

  <dt><code class="sh_javascript">server.close()</code>
  <dd>
    <p>Stops the server. Requests currently in progress will not be
    interrupted.
  </dd>
</dl>
    

<h4 id="http_server_request"><code class="sh_javascript">node.http.ServerRequest</code></h4>

<p> This object is created internally by a HTTP server&mdash;not by the user. 
It is passed as the first argument to the <code
class="sh_javascript">request_handler</code> callback. 

<dl>
  <dt><code class="sh_javascript">req.method</code>
  <dd>The request method as a string. Read only. Example: <code class="sh_javascript">"GET"</code>,
  <code class="sh_javascript">"DELETE"</code>.</dd>

  <dt><code class="sh_javascript">req.uri</code>
  <dd> URI object. Has many fields.
  <dt><code>req.uri.toString()</code>
  <dd> The original URI found in the status line.
  <dt><code>req.uri.anchor</code>
  <dt><code>req.uri.query</code>
  <dt><code>req.uri.file</code>
  <dt><code>req.uri.directory</code>
  <dt><code>req.uri.path</code>
  <dt><code>req.uri.relative</code>
  <dt><code>req.uri.port</code>
  <dt><code>req.uri.host</code>
  <dt><code>req.uri.password</code>
  <dt><code>req.uri.user</code>
  <dt><code>req.uri.authority</code>
  <dt><code>req.uri.protocol</code>
  <dt><code>req.uri.source</code>
  <dt><code>req.uri.queryKey</code>

  <dt><code class="sh_javascript">req.headers</code>
  <dd>The request headers expressed as an array of 2-element arrays. Read only.  
  Example:
<pre class="sh_javascript">
[ ["Content-Length", "123"]
, ["Content-Type", "text/plain"]
, ["Connection", "keep-alive"]
, ["Accept", "*/*"]
]
</pre>

  <dt><code class="sh_javascript">req.http_version</code></dt>
  <dd>The HTTP protocol version as a string. Read only. Examples: <code class="sh_javascript">"1.1"</code>,
  <code class="sh_javascript">"1.0"</code>

  <dt><code class="sh_javascript">req.onBody</code></dt>
  <dd>Callback. Should be set by the user to be informed of when a piece
  of the message body is received. Example:
<pre class="sh_javascript">
req.onBody = function (chunk) {
  puts("part of the body: " + chunk);
};
</pre>
  A chunk of the body is given as the single argument. The transfer-encoding
  has been removed. 

  <p>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
  <code class="sh_javascript">req.setBodyEncoding()</code>.

  <dt><code class="sh_javascript">req.onBodyComplete</code></dt>
  <dd>Callback. Made exactly once for each message. No arguments. After
  <code class="sh_javascript">onBodyComplete</code> is executed <code class="sh_javascript">onBody</code> will no longer be called.
  </dd>

  <dt><code class="sh_javascript">req.setBodyEncoding(encoding)</code></dt>
  <dd>
    Set the encoding for the request body. Either <code class="sh_javascript">"utf8"</code> or
    <code class="sh_javascript">"raw"</code>. Defaults to raw.
    <big>TODO</big>
</dl>

<h4 id="http_server_response"><code class="sh_javascript">node.http.ServerResponse</code></h4>

<dl>
  <dt><code class="sh_javascript">res.sendHeader(status_code, headers)</code></dt>
  <dd>
    Sends a response header to the request. The status code is a 3-digit
    HTTP status code, like <code class="sh_javascript">404</code>. The second argument,
    <code class="sh_javascript">headers</code>, should be an array of 2-element arrays,
    representing the response headers. 

    <p>Example:
<pre class="sh_javascript">
var body = "hello world";
res.sendHeader(200, [ ["Content-Length", body.length]
                    , ["Content-Type", "text/plain"]
                    ]);
</pre>
    This method must only be called once on a message and it must be called
    before <code class="sh_javascript">res.finish()</code> is called.
  </dd>

  <dt><code class="sh_javascript">res.sendBody(chunk)</code></dt>
  <dd>
  This method must be called after <code class="sh_javascript">sendHeader</code> was called. It
  sends a chunk of the response body. This method may be called multiple
  times to provide successive parts of the body.
  </dd>

  <dt><code class="sh_javascript">res.finish()</code></dt>
  <dd>
  This method signals that all of the response headers and body has been
  sent; that server should consider this message complete. 
  The method, <code class="sh_javascript">res.finish()</code>, MUST be called on each response.

</dl>

<h3 id="modules">Modules</h3>

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

<p> As an example, 
<code class="sh_javascript">foo.js</code> loads the module <code class="sh_javascript">mjsunit.js</code>.

<p>The contents of <code class="sh_javascript">foo.js</code>:

<pre class="sh_javascript">
include("mjsunit");
function onLoad () {
  assertEquals(1, 2);
}
</pre>
<p>The contents of <code class="sh_javascript">mjsunit.js</code>:

<pre class="sh_javascript">
function fail (expected, found, name_opt) {
  // ...
}
function deepEquals (a, b) {
  // ...
}
<span class="highlight">exports</span>.assertEquals = function (expected, found, name_opt) {
  if (!deepEquals(found, expected)) {
    fail(expected, found, name_opt);
  }
};
</pre>

<p>Here the module <code class="sh_javascript">mjsunit.js</code> has exported the function
<code class="sh_javascript">assertEquals()</code>.  <code class="sh_javascript">mjsunit.js</code> must be in the
same directory as <code class="sh_javascript">foo.js</code> for <code class="sh_javascript">include()</code> to find it.
The module path is relative to the file calling <code class="sh_javascript">include()</code>.
The module path does not include filename extensions like <code class="sh_javascript">.js</code>.

<p> <code class="sh_javascript">include()</code> inserts the exported objects
from the specified module into the global namespace.

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

<p> To export an object, add to the special <code
  class="highlight">exports</code> object.

<p> The functions <code class="sh_javascript">fail</code> and <code class="sh_javascript">deepEquals</code> are not
exported and remain private to the module.

<p> <code>require()</code> is like <code>include()</code> except does not
polute the global namespace. It returns a namespace object. The exported objects
can only be guaranteed to exist after the <code class="sh_javascript">onLoad()</code> callback is
made. For example:
<pre class="sh_javascript">
var mjsunit = require("mjsunit");
function onLoad () {
  mjsunit.assertEquals(1, 2);
}
</pre>

<p> <code class="sh_javascript">include()</code> and <code class="sh_javascript">require()</code> cannot be used after
<code class="sh_javascript">onLoad()</code> is called. So put them at the beginning of your file.

</body>
</html>