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;
  font-size: 14pt;
  line-height: 120%;
}
#toc ol {
  list-style: none;
  margin: 0;
  padding: 0;
  padding-left: 1em;
}
#toc ol li {
  margin: 0;
  padding: 0;
}
#toc a { color: #aaa; }

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

h1 a { color: inherit; }


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

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="#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>
          <ol>
          <li><a href="#tcp_server">Server</a>
          <li><a href="#tcp_connection">Connection</a>
          </ol>
        <li><a href="#http">HTTP</a>
          <ol>
          <li><a href="#http_server">Server</a>
            <ol>
            <li><a href="#http_server_request">Request</a>
            <li><a href="#http_server_response">Response</a>
            </ol>
          <li><a href="#http_client">Client</a>
            <ol>
            <li><a href="#http_client_request">Request</a>
            <li><a href="#http_client_response">Response</a>
            </ol>
          </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>
Node is an evented sandbox where users cannot execute blocking I/O. 
This is
already natural for Javascript programmers, as the DOM is almost entirely
asynchronous.  The goal is a framework to easily create
efficient network applications.


<p> See <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="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">API</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.

<dl>
  <dt><code class="sh_javascript">puts(string, callback)</code></dt>
  <dd>Outputs the <code>string</code> and a trailing new-line to <code>stdout</code>.
  <p>The <code>callback</code> argument is optional and mostly useless: it will
    notify the user when the operation has completed. Everything in node is
    asynchronous; <code>puts()</code> is no exception. This might seem ridiculous
    but, if for example, one is piping their output into an NFS'd file,
    <code>printf()</code> will block.
    There is an internal queue for <code>puts()</code> output, so you can be assured that
    output will be displayed in the order it was called. 
  </dd>

  <dt><code class="sh_javascript">print(string, callback)</code></dt>
  <dd>Like <code>puts()</code> but without the trailing new-line.</dd>

  <dt><code class="sh_javascript">node.debug(string)</code></dt>
  <dd>A synchronous output function. Will <i>block</i> the process and output the
      string immediately to stdout. Use with care.</dd>
</dl>

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

<dl>
  <dt><code class="sh_javascript">setTimeout(callback, delay)</code></dt>
  <dd> To schedule execution of <code>callback</code> after <code>delay</code>
    milliseconds.  Returns a <code>timeoutId</code> for possible use with
    <code>clearTimeout()</code>.

  <dt><code class="sh_javascript">clearTimeout(timeoutId)</code></dt>
  <dd> Prevents said timeout from triggering.

  <dt><code class="sh_javascript">setInterval(callback, delay)</code></dt>
  <dd> To schedule the repeated execution of <code>callback</code> every
      <code>delay</code> milliseconds.  Returns a <code>intervalId</code> for
      possible use with <code>clearInterval()</code>.

  <dt><code class="sh_javascript">clearInterval(intervalId)</code></dt>
  <dd> Stops a interval from triggering.  </dd>
</dl>

<h3 id="files">node.File</h3>

<p> File system I/O has always been tricky because there are not any portable
non-blocking ways to do it. To get around this, Node uses <a
href="http://software.schmorp.de/pkg/libeio.html">an internal thread pool</a>
to execute file system calls asynchronously.  


<p>All file I/O calls are rather thin wrappers around standard POSIX functions.
All calls have an optional last callback parameter 


<p>Internal request queues exist for each file object so multiple commands can
be issued at once without worry that they will reach the file system out of
order.  Thus the following is safe:
<pre class="sh_javascript">
var file = new node.File();
file.open("/tmp/blah", "w+");
file.write("hello ");
file.write("world");
file.close();</pre>
Additionally there is a process-wide queue for all commands which operate on
the file system directory structure (like <code>rename</code> and
<code>unlink</code>). It's important to understand that all of these request queues are
distinct. If, for example, you do
<pre class="sh_javascript">fileA.write("hello");
fileB.write("world");</pre>
it could be that
first <code>fileB</code> gets written to and then <code>fileA</code> gets written to. 
So if a certain operation order is needed involving multiple files, use the
completion callbacks:
<pre class="sh_javascript">fileA.write("hello", function () {
  fileB.write("world");
});</pre>

<dl>
  <dt><code class="sh_javascript">node.File.rename()</code></dt>
  <dd> 
  </dd>
</dl>


<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 (it does not limit you from
any of HTTP's features). The interface abstracts the transfer-encoding (i.e.
chunked or identity), message boundaries, and persistent connections.

<p> HTTP message headers are represented by an array of 2-element arrays like this
<pre class="sh_javascript">
[ ["Content-Length", "123"]
, ["Content-Type", "text/plain"]
, ["Connection", "keep-alive"]
, ["Accept", "*/*"]
]
</pre>
<p><i>Dictionary-like objects are popularly used to represent HTTP headers but they are
an incorrect abstraction. It is rare, but possible, to have multiple header lines
with the same field. Setting multiple cookies in a single response, for
example, can only be done with multiple <code>Cookie</code> lines.</i>

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

<dl>
  <dt><code class="sh_javascript">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 from accepting new connections.
  </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 to the user 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> Request URI. (Object.) 
  <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.queryKey</code>
  <dt><code>req.uri.toString()</code>, <code>req.uri.source</code>
  <dd> The original URI found in the status line.

  <dt><code class="sh_javascript">req.headers</code>
  <dd>The request headers expressed as an array of 2-element arrays. Read only.  

  <dt><code class="sh_javascript">req.httpVersion</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.
</dl>

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

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


<dl>
  <dt><code class="sh_javascript">res.sendHeader(statusCode, 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>

<h4 id="http_client"><code class="sh_javascript">node.http.Client</code></h4>

<p> An HTTP client is constructed with a server address as its argument, then
the user issues one or more requests.  Depending on the server connected to,
the client might pipeline the requests or reestablish the connection after each
connection. <i>Currently the client does not pipeline requests.</i>

<p> Example of connecting to <code>google.com</code>
<pre class="sh_javascript">
var google = new node.http.Client(80, "google.com");
var req = google.get("/");
req.finish(function (res) {
  puts("STATUS: " + res.statusCode);
  puts("HEADERS: " + JSON.stringify(res.headers));
  res.setBodyEncoding("utf8");
  res.onBody = function (chunk) {
    puts("BODY: " + chunk);
  };
});
</pre>

<dl>
  <dt><code class="sh_javascript">new node.http.Client(port, host);</code></dt>
  <dd> Constructs a new HTTP client. <code>port</code> and <code>host</code>
refer to the server to be connected to. A connection is not established until a
request is issued.
  </dd>

  <dt><code class="sh_javascript">client.get(path, request_headers);</code></dt>
  <dt><code class="sh_javascript">client.head(path, request_headers);</code></dt>
  <dt><code class="sh_javascript">client.post(path, request_headers);</code></dt>
  <dt><code class="sh_javascript">client.del(path, request_headers);</code></dt>
  <dt><code class="sh_javascript">client.put(path, request_headers);</code></dt>
  <dd> Issues a request. 
    <code>request_headers</code> is optional. 
    <code>request_headers</code> should be an array of 2-element arrays. 
    Additional request headers might be added internally by Node.
    Returns a <code>ClientRequest</code> object.

    <p>Important: the request is not complete. This method only sends the
header of the request. One needs to call <code>req.finish()</code> to finalize
the request and retrieve the response.  (This sounds convoluted but it provides
a chance for the user to stream a body to the server with
<code>req.sendBody</code>.  <code>GET</code> and <code>HEAD</code> requests
normally are without bodies but HTTP does not forbid it, so neither do we.)

</dl>

<h4 id="http_client_request"><code class="sh_javascript">node.http.ClientRequest</code></h4>

<p>This object created internally and returned from the request methods of a
<code>node.http.Client</code>. It represents an <i>in-progress</i> request
whose header has already been sent. 

<dl>
  <dt><code class="sh_javascript">req.sendBody(chunk, encoding)</code></dt>
  <dd> Sends a sucessive peice of the body.  By calling this method many times,
the user can stream a request body to a server&mdash;in that case it is
suggested to use the <code class="sh_javascript">["Transfer-Encoding",
"chunked"]</code> header line when creating the request.  

  <p>The <code>chunk</code> argument should be an array of integers or a string.

  <p>The <code>encoding</code> argument is optional and only applies when
    <code>chunk</code> is a string. The encoding argument should be either
    <code>"utf8"</code> or <code>"ascii"</code>. By default the body uses ASCII
    encoding, as it is faster.

  <p> TODO

  <dt><code class="sh_javascript">req.finish(response_handler)</code></dt>

  <dd> Finishes sending the request. If any parts of the body are
    unsent, it will flush them to the socket. If the request is chunked, this
    will send the terminating <code class="sh_javascript">"0\r\n\r\n"</code>.

  <p>The parameter <code>response_handler</code> is a user-supplied callback which will 
    be executed exactly once when the server response headers have been received. 
    The <code>response_handler</code> callback is executed with one argument: a
    <code>ClientResponse</code> object.    
</dl>

<h4 id="http_client_response"><code class="sh_javascript">node.http.ClientResponse</code></h4>

<p>This object is created internally and passed to the
<code>response_handler</code> callback (is given to the client in
<code>req.finish</code> function).  The response object appears exactly as the
header is completely received but before any part of the response body has been
read. 

<dl>
  <dt><code class="sh_javascript">res.statusCode</code></dt>
  <dd>The 3-digit HTTP response status code. (E.G. <code class="sh_javascript">404</code>.)</dd>

  <dt><code class="sh_javascript">res.httpVersion</code></dt>
  <dd>The HTTP version of the connected-to server. Probably either 
      <code class="sh_javascript">"1.1"</code> or 
      <code class="sh_javascript">"1.0"</code>.
  </dd>

  <dt><code class="sh_javascript">res.headers</code></dt>
  <dd>The response headers. An Array of 2-element arrays.</dd>

  <dt><code class="sh_javascript">res.onBody</code></dt>
  <dd>Callback. Should be set by the user to be informed of when a piece
  of the message body is received.
  A chunk of the body is given as the single argument. The transfer-encoding
  has been removed. 

  <p>The body chunk is either a <code>String</code> 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">res.setBodyEncoding()</code>.

  <dt><code class="sh_javascript">res.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">res.setBodyEncoding(encoding)</code></dt>
  <dd>
    Set the encoding for the response body. Either <code class="sh_javascript">"utf8"</code> or
    <code class="sh_javascript">"raw"</code>. Defaults to raw.
  </dd>
</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>