mirror of
https://github.com/nodejs/node.git
synced 2024-11-29 15:06:33 +01:00
527 lines
18 KiB
HTML
527 lines
18 KiB
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 to provide an easy way to 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.
|
|
|
|
<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 (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.
|
|
|
|
<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—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> 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.
|
|
Example:
|
|
<pre class="sh_javascript">
|
|
[ ["Content-Length", "123"]
|
|
, ["Content-Type", "text/plain"]
|
|
, ["Connection", "keep-alive"]
|
|
, ["Accept", "*/*"]
|
|
]
|
|
</pre>
|
|
|
|
<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>
|
|
|
|
<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. (CURRENTLY: The client does not pipeline.)
|
|
|
|
<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—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>
|