mirror of
https://github.com/nodejs/node.git
synced 2024-12-01 16:10:02 +01:00
1076 lines
35 KiB
HTML
1076 lines
35 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<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="style.css" />
|
|
<link type="text/css" rel="stylesheet" href="sh_vim-dark.css" />
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
|
|
<title>node.js</title>
|
|
</head>
|
|
<body onload="sh_highlightDocument();">
|
|
<div id="toc">
|
|
<ol>
|
|
<li><a href="#timers">Timers</a></li>
|
|
<li><a href="#processes">Processes</a></li>
|
|
<li>
|
|
<a href="#files">File I/O</a>
|
|
<ol>
|
|
<li><a href="#file_wrappers">Wrappers</a></li>
|
|
<li><a href="#file_file">File</a></li>
|
|
</ol>
|
|
</li>
|
|
<li>
|
|
<a href="#tcp">TCP</a>
|
|
<ol>
|
|
<li><a href="#tcp_server">Server</a></li>
|
|
<li><a href="#tcp_connection">Connection</a></li>
|
|
</ol>
|
|
</li>
|
|
<li>
|
|
<a href="#http">HTTP</a>
|
|
<ol>
|
|
<li>
|
|
<a href="#http_server">Server</a>
|
|
<ol>
|
|
<li><a href="#http_server_request">Request</a></li>
|
|
<li><a href="#http_server_response">Response</a></li>
|
|
</ol>
|
|
</li>
|
|
<li>
|
|
<a href="#http_client">Client</a>
|
|
<ol>
|
|
<li><a href="#http_client_request">Request</a></li>
|
|
<li><a href="#http_client_response">Response</a></li>
|
|
</ol>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
<li><a href="#modules">Modules</a>
|
|
<ol>
|
|
<li><a href="#onload">onLoad</a></li>
|
|
<li><a href="#onexit">onExit</a></li>
|
|
</ol>
|
|
</ol>
|
|
</div>
|
|
|
|
<div id="content">
|
|
<h1 id="api">Node API</h1>
|
|
<p>
|
|
Conventions: Callbacks are object members which are prefixed with
|
|
<code>on</code>. All methods and members are camel cased. Constructors
|
|
always have a capital first letter.
|
|
</p>
|
|
|
|
<p>
|
|
Node supports 3 byte-string encodings: ASCII (<code>"ascii"</code>),
|
|
UTF-8 (<code>"utf8"</code>), and raw binary (<code>"raw"</code>).
|
|
It uses strings to represent ASCII and UTF-8 encoded data. For
|
|
the moment, arrays of integers are used to represent raw binary
|
|
data—this representation is rather inefficient. This will
|
|
change in the future, when
|
|
<a href="http://code.google.com/p/v8/issues/detail?id=270">
|
|
V8 supports Blob objects
|
|
</a>.
|
|
</p>
|
|
|
|
<p>The following are global functions:</p>
|
|
|
|
<dl>
|
|
<dt><code>puts(string, callback)</code></dt>
|
|
<dd>
|
|
Alias for <code>stdout.puts()</code>. 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 <code>stdout</code> into an
|
|
NFS file, <code>printf()</code> will block from network latency.
|
|
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.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt><code>print(string, callback)</code></dt>
|
|
<dd>Like <code>puts()</code> but without the trailing new-line.</dd>
|
|
|
|
<dt><code>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>
|
|
|
|
<dt><code>node.exit(code)</code></dt>
|
|
<dd>Immediately ends the process with the specified code.</dd>
|
|
|
|
<dt><code>ARGV</code></dt>
|
|
<dd>An array containing the command line arguments.</dd>
|
|
|
|
<dt><code>stdout</code>,
|
|
<code>stderr</code>, and
|
|
<code>stdin</code>
|
|
</dt>
|
|
<dd>Objects of type <code>node.fs.File</code>. (See below)</dd>
|
|
</dl>
|
|
|
|
<h2 id="timers">Timers</h2>
|
|
|
|
<dl>
|
|
<dt><code>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>.
|
|
</dd>
|
|
|
|
<dt><code>clearTimeout(timeoutId)</code></dt>
|
|
<dd>Prevents said timeout from triggering.</dd>
|
|
|
|
<dt><code>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>.
|
|
</dd>
|
|
|
|
<dt><code>clearInterval(intervalId)</code></dt>
|
|
<dd>Stops a interval from triggering.</dd>
|
|
</dl>
|
|
|
|
<h2 id="processes">Processes and IPC</h2>
|
|
|
|
<p>
|
|
Node provides a tridirectional <code>popen(3)</code> facility.
|
|
It is possible to stream data through the child's <code>stdin</code>,
|
|
<code>stdout</code>, and <code>stderr</code> in a fully non-blocking
|
|
way.
|
|
</p>
|
|
|
|
<dl>
|
|
<dt><code>new node.Process(command)</code></dt>
|
|
<dd>Launches a new process with the given <code>command</code>. For example:
|
|
<pre>var ls = new Process("ls -lh /usr");</pre>
|
|
</dd>
|
|
|
|
<dt><code>process.pid</code></dt>
|
|
<dd>The PID of the child process.</dd>
|
|
|
|
<dt><code>process.onOutput = function (chunk) { };</code></dt>
|
|
<dd>A callback to receive output from the process's <code>stdout</code>.
|
|
At the moment the received data is always a string and utf8 encoded.
|
|
(More encodings will be supported in the future.)
|
|
|
|
<p>If the process closes it's <code>stdout</code>, this callback will
|
|
be issued with <code>null</code> as an argument. Be prepared for this
|
|
possibility.
|
|
</dd>
|
|
|
|
<dt><code>process.onError = function (chunk) { };</code></dt>
|
|
<dd>A callback to receive output from the process's <code>stderr</code>.
|
|
At the moment the received data is always a string and utf8 encoded.
|
|
(More encodings will be supported in the future.)
|
|
|
|
<p>If the process closes it's <code>stderr</code>, this callback will
|
|
be issued with <code>null</code> as an argument. Be prepared for this
|
|
possibility.
|
|
</dd>
|
|
|
|
<dt><code>process.onExit = function (exit_code) { };</code></dt>
|
|
<dd>A callback which is called when the sub-process exits. The argument
|
|
is the exit status of the child.
|
|
</dd>
|
|
|
|
<dt><code>process.write(data, encoding="ascii");</code></dt>
|
|
<dd>Write data to the child process's <code>stdin</code>. The second
|
|
argument is optional and specifies the encoding: possible values are
|
|
<code>"utf8"</code>, <code>"ascii"</code>, and <code>"raw"</code>.
|
|
</dd>
|
|
|
|
<dt><code>process.close();</code></dt>
|
|
<dd>Closes the processes <code>stdin</code> stream.</dd>
|
|
|
|
<dt><code>process.kill(signal=node.SIGTERM);</code></dt>
|
|
<dd>Kills the child process with the given signal. If no argument is
|
|
given, the process will be sent <code>node.SIGTERM</code>. The standard
|
|
POSIX signals are defined under the <code>node</code> namespace (e.g.
|
|
<code>node.SIGINT</code>, <code>node.SIGUSR1</code>).
|
|
</dd>
|
|
</dl>
|
|
|
|
<h2 id="files"><code>node.fs</code></h2>
|
|
|
|
<p>
|
|
File I/O is tricky because there are not simple non-blocking ways
|
|
to do it. Node handles file I/O by employing
|
|
<a href="http://software.schmorp.de/pkg/libeio.html">
|
|
an internal thread pool
|
|
</a> to execute file system calls.
|
|
</p>
|
|
|
|
<p>
|
|
This part of the API is split into two parts: simple wrappers
|
|
around standard POSIX file I/O functions and a user-friendly
|
|
<code>File</code> object.
|
|
</p>
|
|
|
|
<h3 id="file_wrappers">POSIX Wrappers</h3>
|
|
|
|
<p>
|
|
All POSIX wrappers have a similar form. They return
|
|
<code>undefined</code> and have a callback called
|
|
<code>on_completion</code> as their last argument. The
|
|
<code>on_completion</code> callback may be passed many parameters,
|
|
but the first parameter is always an integer indicating the error
|
|
status. If the status integer is zero, then the call was successful.
|
|
Example:
|
|
</p>
|
|
<pre>
|
|
node.fs.unlink("/tmp/hello", function (status) {
|
|
if (status == 0)
|
|
puts("successfully deleted /tmp/hello");
|
|
});</pre>
|
|
|
|
<p>
|
|
There is no guaranteed ordering to the POSIX wrappers. The
|
|
following is very much prone to error
|
|
</p>
|
|
<pre>
|
|
node.fs.rename("/tmp/hello", "/tmp/world");
|
|
node.fs.stat("/tmp/world", function (status, stats) {
|
|
puts("stats: " + JSON.stringify(stats));
|
|
});</pre>
|
|
<p>
|
|
because it could be that <code>stat()</code> is executed before
|
|
the <code>rename()</code>. The correct way to do this, is use the
|
|
<code>on_completion</code> callback for <code>rename()</code>
|
|
</p>
|
|
<pre>
|
|
node.fs.rename("/tmp/hello", "/tmp/world", function (status) {
|
|
if (status != 0) return;
|
|
node.fs.stat("/tmp/world", function (status, stats) {
|
|
puts("stats: " + JSON.stringify(stats));
|
|
});
|
|
});</pre>
|
|
|
|
<dl>
|
|
<dt><code>node.fs.rename(path1, path2, on_completion(status))</code></dt>
|
|
<dd> <a href="http://opengroup.org/onlinepubs/007908799/xsh/rename.html">rename(2)</a> </dd>
|
|
|
|
<dt><code>node.fs.stat(path, on_completion(status, stats))</code></dt>
|
|
<dd> <a href="http://opengroup.org/onlinepubs/007908799/xsh/stat.html">stat(2)</a> </dd>
|
|
|
|
<dt><code>node.fs.unlink(path, on_completion(status))</code></dt>
|
|
<dd> <a href="http://opengroup.org/onlinepubs/007908799/xsh/unlink.html">unlink(2)</a> </dd>
|
|
|
|
<dt><code>node.fs.rmdir(path, on_completion(status))</code></dt>
|
|
<dd> <a href="http://opengroup.org/onlinepubs/007908799/xsh/rmdir.html">rmdir(2)</a> </dd>
|
|
|
|
<dt><code>node.fs.close(fd, on_completion(status))</code></dt>
|
|
<dd> <a href="http://opengroup.org/onlinepubs/007908799/xsh/close.html">close(2)</a> </dd>
|
|
|
|
<dt><code>node.fs.open(path, flags, mode, on_completion(status, fd))</code></dt>
|
|
<dd>
|
|
<a href="http://opengroup.org/onlinepubs/007908799/xsh/open.html">open(2)</a>
|
|
<p>
|
|
The constants like <code>O_CREAT</code> are defined at
|
|
<code>node.O_CREAT</code>.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt><code>node.fs.write(fd, data, position, on_completion(status, written))</code></dt>
|
|
<dd>
|
|
Write data to the file specified by <code>fd</code>.
|
|
<p>
|
|
<code>data</code> is either an array of integer (for raw
|
|
data) or a string for UTF-8 encoded characters.
|
|
</p>
|
|
<p>
|
|
<code>position</code> refers to the offset from the beginning
|
|
of the file where this data should be written. If
|
|
<code>null</code>, the data will be written at the current
|
|
position.
|
|
</p>
|
|
<p>See also
|
|
<a href="http://opengroup.org/onlinepubs/007908799/xsh/pwrite.html">pwrite(2)</a>
|
|
</p>
|
|
</dd>
|
|
|
|
<dt><code>node.fs.read(fd, length, position, encoding, on_completion(status, data))</code></dt>
|
|
<dd>
|
|
Read data from the file specified by <code>fd</code>.
|
|
|
|
<p>
|
|
<code>length</code> is an integer specifying the number of
|
|
bytes to read.
|
|
</p>
|
|
|
|
<p>
|
|
<code>position</code> is an integer specifying where to begin
|
|
reading from in the file.
|
|
</p>
|
|
|
|
<p>
|
|
<code>encoding</code> is either <code>node.UTF8</code>
|
|
or <code>node.RAW</code>.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3 id="file_file"><code>node.fs.File</code></h3>
|
|
|
|
<p>Easy buffered file object.</p>
|
|
|
|
<p>
|
|
Internal request queues exist for each file object so that
|
|
multiple commands can be issued at once without worry that they
|
|
will be executed out-of-order. Thus the following is safe:
|
|
</p>
|
|
|
|
<pre>
|
|
var file = new node.fs.File();
|
|
file.open("/tmp/blah", "w+");
|
|
file.write("hello");
|
|
file.write("world");
|
|
file.close();</pre>
|
|
|
|
<p>
|
|
Request queues are local to a single file. If one does
|
|
</p>
|
|
<pre>
|
|
fileA.write("hello");
|
|
fileB.write("world");</pre>
|
|
<p>
|
|
it could be that <code>fileB</code> gets written to before
|
|
<code>fileA</code> is written to. If a certain operation order
|
|
is needed involving multiple files, use the completion callbacks:
|
|
</p>
|
|
<pre>
|
|
fileA.write("hello", function () {
|
|
fileB.write("world");
|
|
});</pre>
|
|
|
|
<dl>
|
|
<dt><code>new node.fs.File(options={})</code></dt>
|
|
<dd>
|
|
Creates a new file object.
|
|
|
|
<p>
|
|
The <code>options</code> argument is optional. It can contain
|
|
the following fields
|
|
</p>
|
|
<ul>
|
|
<li><code>fd</code> — a file descriptor for the file.</li>
|
|
<li>
|
|
<code>encoding</code> — how <code>file.read()</code>
|
|
should return data. Either <code>"raw"</code> or
|
|
<code>"utf8"</code>. Defaults to raw.
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt><code>file.onError = function (method, errno, msg) { }</code></dt>
|
|
<dd>
|
|
Callback. This is called internally anytime an error occurs with
|
|
this file. There are three arguments: the method name, the POSIX
|
|
errno, and a string describing the error.
|
|
|
|
<p>Example</p>
|
|
<pre>
|
|
var path = "/some/path/that/doesnt/exist";
|
|
var file = new node.fs.File();
|
|
file.onError = function (method, errno, msg) {
|
|
stderr.puts("An error occurred calling " + method);
|
|
stderr.puts(msg);
|
|
node.exit(1);
|
|
}
|
|
file.open(path, "w+")</pre>
|
|
</dd>
|
|
|
|
<dt><code>file.open(path, mode, on_completion())</code></dt>
|
|
<dd>
|
|
Opens the file at <code>path</code>.
|
|
<p>
|
|
<code>mode</code> is a string: <code>"r"</code> open for
|
|
reading and writing. <code>"r+"</code> open for only reading.
|
|
<code>"w"</code> create a new file for reading and writing;
|
|
if it already exists truncate it. <code>"w+"</code> create a
|
|
new file for writing only; if it already exists truncate it.
|
|
<code>"a"</code> create a new file for writing and reading.
|
|
Writes append to the end of the file.
|
|
<!-- TODO: Describe mode a+ -->
|
|
<code>"a+"</code>
|
|
<!-- TODO: Describe mode a+ -->
|
|
</p>
|
|
<p>
|
|
The <code>on_completion</code> is a callback that is made
|
|
without arguments when the operation completes. It is optional.
|
|
If an error occurred the <code>on_completion</code> callback
|
|
will not be called, but the <code>file.onError</code> will be
|
|
called.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt><code>file.read(length, position, on_completion(data))</code></dt>
|
|
<dd></dd>
|
|
|
|
<dt><code>file.write(data, position, on_completion(written))</code></dt>
|
|
<dd></dd>
|
|
|
|
<dt><code>file.close(on_completion())</code></dt>
|
|
<dd></dd>
|
|
</dl>
|
|
|
|
<h2 id="tcp"><code>node.tcp</code></h2>
|
|
|
|
<h3 id="tcp_server"><code>node.tcp.Server</code></h3>
|
|
|
|
<p>
|
|
Here is an example of a echo server which listens for connections
|
|
on port 7000
|
|
</p>
|
|
<pre>
|
|
function Echo (socket) {
|
|
socket.setEncoding("utf8");
|
|
socket.onConnect = function () {
|
|
socket.send("hello\r\n");
|
|
};
|
|
socket.onReceive = function (data) {
|
|
socket.send(data);
|
|
};
|
|
socket.onEOF = function () {
|
|
socket.send("goodbye\r\n");
|
|
socket.close();
|
|
};
|
|
}
|
|
var server = new node.tcp.Server(Echo, {backlog: 1024});
|
|
server.listen(7000, "localhost");</pre>
|
|
|
|
<dl>
|
|
<dt><code>new node.tcp.Server(connection_handler(socket), options={});</code></dt>
|
|
<dd>
|
|
Creates a new TCP server.
|
|
|
|
<p>
|
|
<code>connection_handler</code> is a callback which is called
|
|
on each connection. It is given one argument: an instance of
|
|
<code>node.tcp.Connection</code>.
|
|
</p>
|
|
|
|
<p>
|
|
<code>options</code> for now only supports one option:
|
|
<code>backlog</code> which should be an integer and describes
|
|
how large of a connection backlog the operating system should
|
|
maintain for this server. The <code>backlog</code> defaults
|
|
to 1024.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt><code>server.listen(port, host=null)</code></dt>
|
|
<dd>
|
|
Tells the server to listen for TCP connections to <code>port</code>
|
|
and <code>host</code>. Note, <code>host</code> is optional. If
|
|
<code>host</code> is not specified the server will accept
|
|
connections to any IP address on the specified port.
|
|
</dd>
|
|
|
|
<dt><code>server.close()</code></dt>
|
|
<dd> Stops the server from accepting new connections. </dd>
|
|
</dl>
|
|
|
|
<h3 id="tcp_connection"><code>node.tcp.Connection</code></h3>
|
|
|
|
<p>
|
|
This object is used as a TCP client and also as a server-side
|
|
socket for <code>node.tcp.Server</code>s.
|
|
</p>
|
|
|
|
<dl>
|
|
<dt><code>new node.tcp.Connection()</code></dt>
|
|
<dd>Creates a new connection object.</dd>
|
|
|
|
<dt><code>connection.connect(port, host="127.0.0.1")</code></dt>
|
|
<dd>
|
|
Opens a connection to the specified <code>port</code> and
|
|
<code>host</code>. If the second parameter is omitted, localhost is
|
|
assumed.
|
|
</dd>
|
|
|
|
<dt><code>connection.remoteAddress</code></dt>
|
|
<dd>
|
|
The string representation of the remote IP address. For example,
|
|
<code>"74.125.127.100"</code> or <code>"2001:4860:a005::68"</code>.
|
|
|
|
<p>This member is only present in server-side connections.</p>
|
|
</dd>
|
|
|
|
<dt><code>connection.readyState</code></dt>
|
|
<dd>
|
|
Either <code>"closed"</code>, <code>"open"</code>, <code>"opening"</code>
|
|
<code>"readOnly"</code>, or <code>"writeOnly"</code>.
|
|
</dd>
|
|
|
|
<dt><code>connection.setEncoding(encoding)</code></dt>
|
|
<dd>
|
|
Sets the encoding (either <code>"utf8"</code> or
|
|
<code>"raw"</code>) for data that is received.
|
|
</dd>
|
|
|
|
<dt><code>connection.send(data, encoding="ascii")</code></dt>
|
|
<dd>
|
|
Sends data on the connection. The data should be eithre an array
|
|
of integers (for raw binary) or a string (for utf8 or ascii).
|
|
The second parameter specifies the encoding in the case of a
|
|
string—it defaults to ASCII because encoding to UTF8 is
|
|
rather slow.
|
|
</dd>
|
|
|
|
<dt><code>connection.close()</code></dt>
|
|
<dd>
|
|
Half-closes the connection. I.E. sends a FIN packet. It is
|
|
possible the server will still send some data. After calling
|
|
this <code>readyState</code> will be <code>"readOnly"</code>.
|
|
</dd>
|
|
|
|
<dt><code>connection.fullClose()</code></dt>
|
|
<dd>
|
|
Close both ends of the connection. Data that is received
|
|
after this call is responded to with RST packets. If you don't
|
|
know about this, just use <code>close()</code>.
|
|
</dd>
|
|
|
|
<dt><code>connection.forceClose()</code></dt>
|
|
<dd>
|
|
Ensures that no more I/O activity happens on this socket. Only
|
|
necessary in case of errors (parse error or so).
|
|
</dd>
|
|
|
|
<dt><code>connection.onConnect = function () { };</code></dt>
|
|
<dd>Call once the connection is established.</dd>
|
|
|
|
<dt><code>connection.onReceive = function (data) { };</code></dt>
|
|
<dd>
|
|
Called when data is received on the connection. Encoding of data
|
|
is set by <code>connection.setEncoding()</code>.
|
|
<code>data</code> will either be a string, in the case of utf8,
|
|
or an array of integer in the case of raw encoding.
|
|
</dd>
|
|
|
|
<dt><code>connection.onEOF = function () { };</code></dt>
|
|
<dd>
|
|
Called when the other end of the connection sends a FIN packet.
|
|
<code>onReceive</code> will not be called after this. After
|
|
receiving this <code>readyState</code> will be
|
|
<code>"writeOnly"</code>. You should probably just call
|
|
<code>connection.close()</code> in this callback.
|
|
</dd>
|
|
|
|
<dt><code>connection.onDisconnect = function (had_error) { };</code></dt>
|
|
<dd>
|
|
Called once the connection is fully disconnected.
|
|
|
|
<p>
|
|
The callback is passed one boolean argument <code>had_error</code>.
|
|
This lets one know if the connect was closed due to an error.
|
|
(TODO: look up error codes.)
|
|
</p>
|
|
</dd>
|
|
|
|
<dt><code>connection.onError = function () { };</code></dt>
|
|
<dd>Called on an error.</dd>
|
|
</dl>
|
|
|
|
<h2 id="http"><code>node.http</code></h2>
|
|
|
|
<p>
|
|
The HTTP interfaces here are designed to support many features
|
|
of the protocol which have been traditionally difficult to handle.
|
|
In particular, large, possibly chunked, messages. The interface is
|
|
careful to never buffer entire requests or responses—the
|
|
user is able to stream data.
|
|
</p>
|
|
|
|
<p>
|
|
HTTP message headers are represented by an array of 2-element
|
|
arrays like this
|
|
</p>
|
|
<pre>
|
|
[ ["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></p>
|
|
|
|
<h3 id="http_server"><code>node.http.Server</code></h3>
|
|
|
|
<dl>
|
|
<dt><code>new node.http.Server(request_handler, options);</code></dt>
|
|
<dd>
|
|
<p>Creates a new web server.</p>
|
|
|
|
<p>
|
|
The <code>options</code> argument is optional. The
|
|
<code>options</code> argument accepts the same values as the
|
|
options argument for <code>node.tcp.Server</code> does.
|
|
</p>
|
|
|
|
<p>
|
|
The <code>request_handler</code> is a callback which is made
|
|
on each request with a <code>ServerRequest</code> and
|
|
<code>ServerResponse</code> arguments.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt><code>server.listen(port, hostname)</code></dt>
|
|
<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.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt><code>server.close()</code></dt>
|
|
<dd>
|
|
<p>Stops the server from accepting new connections.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3 id="http_server_request"><code>node.http.ServerRequest</code></h3>
|
|
|
|
<p>
|
|
This object is created internally by a HTTP server—not by
|
|
the user. It is passed to the user as the first argument to the
|
|
<code>request_handler</code> callback.
|
|
</p>
|
|
|
|
<dl>
|
|
<dt><code>req.method</code></dt>
|
|
<dd>The request method as a string. Read only. Example:
|
|
<code>"GET"</code>, <code>"DELETE"</code>.
|
|
</dd>
|
|
|
|
<dt><code>req.uri</code></dt>
|
|
<dd> Request URI. (Object.)</dd>
|
|
<dt><code>req.uri.anchor</code></dt>
|
|
<dt><code>req.uri.query</code></dt>
|
|
<dt><code>req.uri.file</code></dt>
|
|
<dt><code>req.uri.directory</code></dt>
|
|
<dt><code>req.uri.path</code></dt>
|
|
<dt><code>req.uri.relative</code></dt>
|
|
<dt><code>req.uri.port</code></dt>
|
|
<dt><code>req.uri.host</code></dt>
|
|
<dt><code>req.uri.password</code></dt>
|
|
<dt><code>req.uri.user</code></dt>
|
|
<dt><code>req.uri.authority</code></dt>
|
|
<dt><code>req.uri.protocol</code></dt>
|
|
<dt><code>req.uri.params</code></dt>
|
|
<dt>
|
|
<code>req.uri.toString()</code>,
|
|
<code>req.uri.source</code>
|
|
</dt>
|
|
<dd>The original URI found in the status line.</dd>
|
|
|
|
<dt><code>req.headers</code></dt>
|
|
<dd>
|
|
The request headers expressed as an array of 2-element arrays.
|
|
Read only.
|
|
</dd>
|
|
|
|
<dt><code>req.httpVersion</code></dt>
|
|
<dd>
|
|
The HTTP protocol version as a string. Read only. Examples:
|
|
<code>"1.1"</code>, <code>"1.0"</code>
|
|
</dd>
|
|
|
|
<dt><code>req.onBody = function (chunk) { }; </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>
|
|
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 decoded.
|
|
|
|
<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>req.setBodyEncoding()</code>.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt><code>req.onBodyComplete = function () { };</code></dt>
|
|
<dd>
|
|
Callback. Made exactly once for each message. No arguments.
|
|
After <code>onBodyComplete</code> is executed
|
|
<code>onBody</code> will no longer be called.
|
|
</dd>
|
|
|
|
<dt><code>req.setBodyEncoding(encoding)</code></dt>
|
|
<dd>
|
|
Set the encoding for the request body. Either <code>"utf8"</code>
|
|
or <code>"raw"</code>. Defaults to raw.
|
|
</dd>
|
|
|
|
<dt><code>req.interrupt()</code></dt>
|
|
<dd>
|
|
Interrupt the request. You will not receive anymore callbacks.
|
|
This is useful if, for example someone is streaming up a file but it
|
|
is too large and neesd to be stopped. The connection to the client
|
|
will be closed immediately.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3 id="http_server_response"><code>node.http.ServerResponse</code></h3>
|
|
|
|
<p>
|
|
This object is created internally by a HTTP server—not by
|
|
the user. It is passed to the user as the second argument to the
|
|
<code>request_handler</code> callback.
|
|
</p>
|
|
|
|
<dl>
|
|
<dt><code>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>404</code>. The second
|
|
argument, <code>headers</code>, should be an array of 2-element
|
|
arrays, representing the response headers.
|
|
|
|
<p>Example:</p>
|
|
<pre>
|
|
var body = "hello world";
|
|
res.sendHeader(200, [ ["Content-Length", body.length]
|
|
, ["Content-Type", "text/plain"]
|
|
]);</pre>
|
|
<p>
|
|
This method must only be called once on a message and it must
|
|
be called before <code>res.finish()</code> is called.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt><code>res.sendBody(chunk, encoding="ascii")</code></dt>
|
|
<dd>
|
|
This method must be called after <code>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.
|
|
|
|
<p>
|
|
If <code>chunk</code> is a string, the second parameter
|
|
specifies how to encode it into a byte stream. By default the
|
|
<code>encoding</code> is <code>"ascii"</code>.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt><code>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>res.finish()</code>, MUST be called on each
|
|
response.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3 id="http_client"><code>node.http.Client</code></h3>
|
|
|
|
<p>
|
|
An HTTP client is constructed with a server address as its
|
|
argument, the returned handle is then used to issue 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 implementation does not pipeline requests.</i>
|
|
</p>
|
|
|
|
<p> Example of connecting to <code>google.com</code></p>
|
|
<pre>
|
|
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>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>client.get(path, request_headers);</code></dt>
|
|
<dt><code>client.head(path, request_headers);</code></dt>
|
|
<dt><code>client.post(path, request_headers);</code></dt>
|
|
<dt><code>client.del(path, request_headers);</code></dt>
|
|
<dt><code>client.put(path, request_headers);</code></dt>
|
|
<dd>
|
|
Issues a request; if necessary establishes connection.
|
|
|
|
<p>
|
|
<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>
|
|
|
|
<p>
|
|
Do remember to include the <code>Content-Length</code> header if you
|
|
plan on sending a body. If you plan on streaming the body, perhaps
|
|
set <code>Transfer-Encoding: chunked</code>.
|
|
</p>
|
|
|
|
<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>.)
|
|
</p>
|
|
|
|
<p><i>
|
|
<code>GET</code> and <code>HEAD</code> requests normally are
|
|
without bodies but HTTP does not forbid it, so neither do we.
|
|
</i></p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3 id="http_client_request"><code>node.http.ClientRequest</code></h3>
|
|
|
|
<p>
|
|
This object is 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.
|
|
</p>
|
|
|
|
<dl>
|
|
<dt><code>req.sendBody(chunk, encoding="ascii")</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>["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>
|
|
|
|
<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>
|
|
</dd>
|
|
<dt><code>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>"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.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3 id="http_client_response"><code>node.http.ClientResponse</code></h3>
|
|
|
|
<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.
|
|
</p>
|
|
|
|
<dl>
|
|
<dt><code>res.statusCode</code></dt>
|
|
<dd>The 3-digit HTTP response status code. E.G. <code>404</code>.</dd>
|
|
|
|
<dt><code>res.httpVersion</code></dt>
|
|
<dd>
|
|
The HTTP version of the connected-to server. Probably either
|
|
<code>"1.1"</code> or <code>"1.0"</code>.
|
|
</dd>
|
|
|
|
<dt><code>res.headers</code></dt>
|
|
<dd>The response headers. An Array of 2-element arrays.</dd>
|
|
|
|
<dt><code>res.onBody</code></dt>
|
|
<dd>
|
|
Callback. Should be set by the user to be informed of when a
|
|
piece of the response 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>res.setBodyEncoding()</code>.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt><code>res.onBodyComplete</code></dt>
|
|
<dd>
|
|
Callback. Made exactly once for each message. No arguments.
|
|
After <code>onBodyComplete</code> is executed
|
|
<code>onBody</code> will no longer be called.
|
|
</dd>
|
|
|
|
<dt><code>res.setBodyEncoding(encoding)</code></dt>
|
|
<dd>
|
|
Set the encoding for the response body. Either
|
|
<code>"utf8"</code> or <code>"raw"</code>. Defaults to raw.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h2 id="modules">Modules</h2>
|
|
|
|
<p>
|
|
Node has a simple module loading system. In Node, files and
|
|
modules are in one-to-one correspondence. As an example,
|
|
<code>foo.js</code> loads the module <code>mjsunit.js</code>.
|
|
</p>
|
|
|
|
<p>The contents of <code>foo.js</code>:</p>
|
|
|
|
<pre>
|
|
include("mjsunit.js");
|
|
function onLoad () {
|
|
assertEquals(1, 2);
|
|
}</pre>
|
|
<p>The contents of <code>mjsunit.js</code>:</p>
|
|
|
|
<pre>
|
|
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);
|
|
}
|
|
};</pre>
|
|
|
|
<p>
|
|
The module <code>mjsunit.js</code> has exported a function
|
|
<code>assertEquals()</code>. <code>mjsunit.js</code> must be
|
|
in the same directory as <code>foo.js</code> for
|
|
<code>include()</code> to find it. The module path is relative
|
|
to the file calling <code>include()</code>.
|
|
</p>
|
|
|
|
<p>Alternatively one can use HTTP URLs to load modules. For example,
|
|
|
|
<pre>include("http://tinyclouds.org/node/mjsunit.js");</pre>
|
|
|
|
<p>
|
|
<code>include()</code> inserts the exported objects from the
|
|
specified module into the global namespace.
|
|
</p>
|
|
|
|
<h3 id="onload"><code>onLoad</code></h3>
|
|
|
|
<p>
|
|
Because module loading does not happen instantaneously, and
|
|
because Node has a policy of never blocking, a callback
|
|
<code>onLoad</code> can be set that will notify the user when the
|
|
included modules are loaded. Each file/module can have an
|
|
<code>onLoad</code> callback.
|
|
</p>
|
|
|
|
<p>
|
|
To export an object, add to the special <code>exports</code>
|
|
object.
|
|
The functions <code>fail</code> and
|
|
<code>deepEquals</code> are not exported and remain private to
|
|
the module.
|
|
|
|
Alternatively, one can use <code>this</code> instead of
|
|
<code>exports</code>.
|
|
</p>
|
|
|
|
<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>onLoad()</code> callback is made. For example:
|
|
</p>
|
|
<pre>
|
|
var mjsunit = require("mjsunit.js");
|
|
function onLoad () {
|
|
mjsunit.assertEquals(1, 2);
|
|
}</pre>
|
|
|
|
<p>
|
|
<code>include()</code> and <code>require()</code> cannot be
|
|
used after <code>onLoad()</code> is called.
|
|
</p>
|
|
|
|
<h3 id="onexit"><code>onExit</code></h3>
|
|
|
|
<p>
|
|
When the program exits a callback <code>onExit()</code> will be
|
|
called for each module (children first).
|
|
</p>
|
|
|
|
<p>
|
|
The <code>onExit()</code> callback cannot perform I/O as the process is
|
|
going to forcably exit in several microseconds, however it is a good
|
|
hook to perform some constant time checks of the module's state.
|
|
It's useful for unit tests.
|
|
</p>
|
|
|
|
<pre>
|
|
include("mjsunit.js");
|
|
|
|
var timer_executed = false;
|
|
|
|
setTimeout(function () {
|
|
timer_executed = true
|
|
}, 1000);
|
|
|
|
function onExit () {
|
|
assertTrue(timer_executed);
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
Just to reiterate: <code>onExit()</code>, is not the place to close
|
|
files or shutdown servers. The process will exit before they get
|
|
performed.
|
|
</p>
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|