mirror of https://github.com/lukechilds/node.git
Ryan
16 years ago
3 changed files with 846 additions and 840 deletions
@ -0,0 +1,768 @@ |
|||
<html> |
|||
<style> |
|||
</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="style.css"> |
|||
<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="#timers">Timers</a> |
|||
<li><a href="#files">File I/O</a> |
|||
<ol> |
|||
<li><a href="#file_wrappers">Wrappers</a> |
|||
<li><a href="#file_file">File</a> |
|||
</ol> |
|||
<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> |
|||
</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> |
|||
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>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. |
|||
</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> |
|||
</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>. |
|||
|
|||
<dt><code>clearTimeout(timeoutId)</code></dt> |
|||
<dd> Prevents said timeout from triggering. |
|||
|
|||
<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>. |
|||
|
|||
<dt><code>clearInterval(intervalId)</code></dt> |
|||
<dd> Stops a interval from triggering. </dd> |
|||
</dl> |
|||
|
|||
<h2 id="files">node.fs</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>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. |
|||
|
|||
<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: |
|||
<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 |
|||
<pre> |
|||
node.fs.rename("/tmp/hello", "/tmp/world"); |
|||
node.fs.stat("/tmp/world", function (status, stats) { |
|||
puts("stats: " + JSON.stringify(stats)); |
|||
}); |
|||
</pre> |
|||
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> |
|||
<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.constants.O_CREAT</code>. |
|||
</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><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>See also <a href="http://opengroup.org/onlinepubs/007908799/xsh/pwrite.html">pwrite(2)</a> |
|||
|
|||
</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><code>position</code> is an integer specifying where to begin reading |
|||
from in the file. |
|||
|
|||
<p><code>encoding</code> is either <code>node.constants.UTF8</code> or |
|||
<code>node.constants.RAW</code>. |
|||
</dt> |
|||
</dl> |
|||
|
|||
<h3 id="file_file"><code>node.fs.File</code></h3> |
|||
|
|||
<p>Easy buffered file object. |
|||
|
|||
<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: |
|||
|
|||
<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 |
|||
<pre>fileA.write("hello"); |
|||
fileB.write("world");</pre> |
|||
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: |
|||
<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 |
|||
<ul> |
|||
<li><code>fd</code> — a file descriptor for the file. |
|||
<li><code>encoding</code> — how <code>file.read()</code> should return |
|||
data. Either <code>"raw"</code> or <code>"utf8"</code>. Defaults to raw. |
|||
</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> |
|||
|
|||
<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. |
|||
<code>"a+"</code> |
|||
<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. |
|||
</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 |
|||
<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><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. |
|||
</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. |
|||
|
|||
<dl> |
|||
<dt><code>new node.tcp.Connection()</code></dt> |
|||
<dd>Creates a new connection object. |
|||
</dd> |
|||
|
|||
<dt><code>connection.readyState</code></dt> |
|||
<dd>Either <code>"closed"</code>, <code>"open"</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>conneciton.onConnect = function () { };</code></dt> |
|||
<dd>Call once the connection is established.</dd> |
|||
|
|||
<dt><code>conneciton.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>conneciton.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. |
|||
|
|||
<dt><code>conneciton.onDisconnect = function () { };</code></dt> |
|||
<dd>Called once the connection is fully disconnected.</dd> |
|||
|
|||
<dt><code>conneciton.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> HTTP message headers are represented by an array of 2-element arrays like this |
|||
<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> |
|||
|
|||
<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> |
|||
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>The <code>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>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>server.close()</code> |
|||
<dd> |
|||
<p>Stops the server from accepting new connections. |
|||
</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. |
|||
|
|||
<dl> |
|||
<dt><code>req.method</code> |
|||
<dd>The request method as a string. Read only. Example: <code>"GET"</code>, |
|||
<code>"DELETE"</code>.</dd> |
|||
|
|||
<dt><code>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>req.headers</code> |
|||
<dd>The request headers expressed as an array of 2-element arrays. Read only. |
|||
|
|||
<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> |
|||
|
|||
<dt><code>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> |
|||
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>. |
|||
|
|||
<dt><code>req.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>req.setBodyEncoding(encoding)</code></dt> |
|||
<dd> |
|||
Set the encoding for the request body. Either <code>"utf8"</code> or |
|||
<code>"raw"</code>. Defaults to raw. |
|||
</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. |
|||
|
|||
|
|||
<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: |
|||
<pre> |
|||
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>res.finish()</code> is called. |
|||
</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>. |
|||
</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. |
|||
|
|||
</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> Example of connecting to <code>google.com</code> |
|||
<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>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><i> <code>GET</code> and |
|||
<code>HEAD</code> requests normally are without bodies but HTTP does not forbid |
|||
it, so neither do we.</i> |
|||
|
|||
</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. |
|||
|
|||
<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>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. |
|||
|
|||
<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. |
|||
</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. |
|||
|
|||
<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>. |
|||
|
|||
<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. |
|||
|
|||
<p> As an example, |
|||
<code>foo.js</code> loads the module <code>mjsunit.js</code>. |
|||
|
|||
<p>The contents of <code>foo.js</code>: |
|||
|
|||
<pre> |
|||
include("mjsunit"); |
|||
function onLoad () { |
|||
assertEquals(1, 2); |
|||
} |
|||
</pre> |
|||
<p>The contents of <code>mjsunit.js</code>: |
|||
|
|||
<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>Here the module <code>mjsunit.js</code> has exported the 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>. |
|||
The module path does not include filename extensions like <code>.js</code>. |
|||
|
|||
<p> <code>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 |
|||
>onLoad</code> can be set and will notify the user |
|||
when all the included modules are loaded. Each file/module can have an <code |
|||
>onLoad</code> callback. |
|||
|
|||
<p>To export an object, add to the special <code>exports</code> object. |
|||
|
|||
<p> The functions <code>fail</code> and <code>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>onLoad()</code> callback is |
|||
made. For example: |
|||
<pre> |
|||
var mjsunit = require("mjsunit"); |
|||
function onLoad () { |
|||
mjsunit.assertEquals(1, 2); |
|||
} |
|||
</pre> |
|||
|
|||
<p> <code>include()</code> and <code>require()</code> cannot be used after |
|||
<code>onLoad()</code> is called. So put them at the beginning of your file. |
|||
|
|||
</body> |
|||
</html> |
|||
@ -0,0 +1,73 @@ |
|||
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 8em; |
|||
} |
|||
#toc { |
|||
position: fixed; |
|||
top: 2em; |
|||
left: 0; |
|||
width: 8em; |
|||
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 code, h2 code, h3 code, h4 code, |
|||
h1 a, h2 a, h3 a, h4 a |
|||
{ |
|||
color: inherit; |
|||
font-size: inherit; |
|||
} |
|||
|
|||
pre, code { |
|||
font-family: monospace; |
|||
font-size: 14pt; |
|||
color: #fee; |
|||
} |
|||
|
|||
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; |
|||
} |
|||
|
|||
Loading…
Reference in new issue