diff options
author | Urban Hafner <urban@bettong.net> | 2009-06-05 14:23:51 +0400 |
---|---|---|
committer | Urban Hafner <urban@bettong.net> | 2009-06-05 14:23:51 +0400 |
commit | 565becb8ad61e41e3b21c9d23a45004951e7ec6e (patch) | |
tree | 8e4df847d1d12fdab3a8e0e9e3303929c29f7cb5 /website | |
parent | 9e6603476aa262bf92dd723cf8a224d76ca2db99 (diff) |
XHTML compliant HTML and a few spelling fixes
Diffstat (limited to 'website')
-rw-r--r-- | website/api.html | 1466 | ||||
-rw-r--r-- | website/index.html | 344 |
2 files changed, 998 insertions, 812 deletions
diff --git a/website/api.html b/website/api.html index 63486fd1e84..95e98f27f80 100644 --- a/website/api.html +++ b/website/api.html @@ -1,251 +1,314 @@ -<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> +<!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><a href="#files">File I/O</a> + <li><a href="#timers">Timers</a></li> + <li> + <a href="#files">File I/O</a> <ol> - <li><a href="#file_wrappers">Wrappers</a> - <li><a href="#file_file">File</a> + <li><a href="#file_wrappers">Wrappers</a></li> + <li><a href="#file_file">File</a></li> </ol> - <li><a href="#tcp">TCP</a> + </li> + <li> + <a href="#tcp">TCP</a> <ol> - <li><a href="#tcp_server">Server</a> - <li><a href="#tcp_connection">Connection</a> + <li><a href="#tcp_server">Server</a></li> + <li><a href="#tcp_connection">Connection</a></li> </ol> - <li><a href="#http">HTTP</a> + </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><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> + <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><a href="#modules">Modules</a> + </li> + <li><a href="#modules">Modules</a></li> </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> + </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> -<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"><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>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> + <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> +});</pre> -<p>There is no guaranteed ordering to the POSIX wrappers. The following is -very much prone to error -<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> -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> +});</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> +});</pre> - <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> + <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.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.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.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. + <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> - <p>See also <a href="http://opengroup.org/onlinepubs/007908799/xsh/pwrite.html">pwrite(2)</a> + <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> - </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.read(fd, length, position, encoding, on_completion(status, data))</code></dt> - <dd> Read data from the file specified by <code>fd</code>. + <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>. + </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> + <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> + <code>position</code> is an integer specifying where to begin + reading from in the file. + </p> - <p><code>encoding</code> is either <code>node.constants.UTF8</code> or - <code>node.constants.RAW</code>. - </dt> -</dl> + <p> + <code>encoding</code> is either <code>node.constants.UTF8</code> + or <code>node.constants.RAW</code>. + </p> + </dd> + </dl> -<h3 id="file_file"><code>node.fs.File</code></h3> + <h3 id="file_file"><code>node.fs.File</code></h3> -<p>Easy buffered file object. + <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> + 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> + <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"); + <p> + Request queues are local to a single file. If one does + </p> + <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 () { + <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 - <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> + <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) { @@ -253,48 +316,52 @@ file.onError = function (method, errno, msg) { 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> +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 () { @@ -309,280 +376,331 @@ function Echo (socket) { }; } 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 (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.) - </dd> +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.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>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>conneciton.onError = function () { };</code></dt> - <dd>Called on an error.</dd> -</dl> + <dt><code>connection.onError = function () { };</code></dt> + <dd>Called on an error.</dd> + </dl> -<h2 id="http"><code>node.http</code></h2> + <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> + 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 -<pre> + <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> +]</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> -<h3 id="http_server"><code>node.http.Server</code></h3> + <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> -<dl> - <dt><code>new node.http.Server(request_handler, options);</code></dt> - <dd> - <p>Creates a new web server. + <dt><code>server.close()</code></dt> + <dd> + <p>Stops the server from accepting new connections.</p> + </dd> + </dl> - <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> -<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.params</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> + <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</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> +};</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</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> + </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> - 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> + ]);</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) { @@ -592,135 +710,162 @@ req.finish(function (res) { 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. +});</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> + 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> - <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. -As an example, -<code>foo.js</code> loads the module <code>mjsunit.js</code>. - -<p>The contents of <code>foo.js</code>: - -<pre> + 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"); function onLoad () { assertEquals(1, 2); -} -</pre> -<p>The contents of <code>mjsunit.js</code>: +}</pre> + <p>The contents of <code>mjsunit.js</code>:</p> -<pre> + <pre> function fail (expected, found, name_opt) { // ... } @@ -731,41 +876,54 @@ exports.assertEquals = function (expected, found, name_opt) { if (!deepEquals(found, expected)) { fail(expected, found, name_opt); } -}; -</pre> - -<p>The module <code>mjsunit</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>. -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 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. -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> +};</pre> + + <p> + The module <code>mjsunit</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>. The module path does + not include filename extensions like <code>.js</code>. + </p> + + <p> + <code>include()</code> inserts the exported objects from the + specified module into the global namespace. + </p> + + <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 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. + </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"); 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. +}</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. + </p> +</div> </body> </html> diff --git a/website/index.html b/website/index.html index b9fde3a7dfd..1662d0c5a16 100644 --- a/website/index.html +++ b/website/index.html @@ -1,38 +1,45 @@ -<html> -<style> - ul { - padding: 0; - margin: 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="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="#audience">Audience</a></li> - <li><a href="#about">About</a></li> - <li><a href="#download">Download</a></li> - <li><a href="#build">Build</a></li> - <li><a href="#community">Community</a></li> - <li><a href="api.html">Documentation</a></li> - </ol> -</div> -<div id="content"> - -<h1><a href="http://tinyclouds.org/node">Node</a></h1> - -<p id="introduction">Purely event-based I/O for <a - href="http://code.google.com/p/v8/">V8 javascript</a>. - -<p>An example of a web server written with Node which responds with -"Hello World" after waiting two seconds: - -<pre> +<!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> + <style type="text/css"> + ul { + padding: 0; + margin: 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="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="#audience">Audience</a></li> + <li><a href="#about">About</a></li> + <li><a href="#download">Download</a></li> + <li><a href="#build">Build</a></li> + <li><a href="#community">Community</a></li> + <li><a href="api.html">Documentation</a></li> + </ol> + </div> + <div id="content"> + + <h1><a href="http://tinyclouds.org/node">Node</a></h1> + + <p id="introduction"> + Purely event-based I/O for + <a href="http://code.google.com/p/v8/">V8 javascript</a>. + </p> + + <p> + An example of a web server written with Node which responds with + "Hello World" after waiting two seconds: + </p> + + <pre> new node.http.Server(function (req, res) { setTimeout(function () { res.sendHeader(200, [["Content-Type", "text/plain"]]); @@ -40,135 +47,156 @@ new node.http.Server(function (req, res) { res.finish(); }, 2000); }).listen(8000); -puts("Server running at http://127.0.0.1:8000/"); -</pre> - -<p> To run the server, put the code into a file <code>example.js</code> -and execute it with the <code>node</code> program -<pre class="sh_none">% /usr/local/bin/node example.js -Server running at http://127.0.0.1:8000/ -</pre> - -<p> See the <a href="api.html">API documentation</a> for more examples. - -<h2 id="audience">Audience</h2> - -<p>This project is for those interested in -<ul> -<li>server-side javascript -<li>developing evented servers -<li>developing new web frameworks -</ul> - -<h2 id="about">About</h2> - -<p> Node's goal is to provide an easy way to build scalable network -programs. -In the above example, the 2 second delay does not prevent the server from -handling new requests. -Node tells the operating system (through -<code>epoll</code>, -<code>kqueue</code>, -<code class="sh_none">/dev/poll</code>, -or <code>select</code>) -that it should be notified when the 2 seconds are up or if a new connection -is made—then it goes to sleep. If someone new connects, then it -executes the callback, if the timeout expires, it executes the inner -callback. Each connection is only a small heap allocation. - -<p>This is in contrast to today's more common model -where OS threads are employed for concurrency. Thread-based networking -<a href="http://www.sics.se/~joe/apachevsyaws.html">is</a> -<a href="http://www.kegel.com/c10k.html">relatively</a> -<a href="http://bulk.fefe.de/scalable-networking.pdf">inefficient</a> -<!-- TODO needs links --> -and -very -difficult -to -use. - -Node will show much better memory efficiency under high-loads -<!-- TODO benchmark --> -than systems which allocate 2mb thread stacks for each connection. - -Furthermore, users of Node are free from worries of dead-locking the -process—there are no locks. No function in Node directly performs -I/O, so the process never blocks. Because nothing blocks, less-than-expert -programmers are able to develop fast systems. - -<p>Node is similar in design to systems like -Ruby's <a href="http://rubyeventmachine.com/">Event Machine</a> -or -Python's <a href="http://twistedmatrix.com/">Twisted</a>. -Node takes the event model a bit further. For example, in other systems -there is always a blocking call to start the event-loop. Typically one -defines behavior through callbacks at the beginning of a script and at the -end starts a server through a call like <code>EventMachine::run()</code>. -In Node it works differently. By default Node enters the event loop after -executing the input script. Node exits the event loop when there are no more -callbacks to perform. Like in traditional browser javascript, the event loop -is hidden from the user. - -<p>Node's HTTP API has grown out of my difficulties developing and working -with web servers. For example, streaming data through most web frameworks is -impossible. Or the oft-made false assumption that all message headers have -unique fields. Node attempts to correct these and other problems in its -API. Coupled with Node's purely evented infrastructure, it will make a -more comprehensive foundation for future web libraries/frameworks. - -<p> <i>But what about multiple-processor concurrency? Threads are necessary -to scale programs to multi-core computers.</i> The name <i>Node</i> should -give some hint at how it is envisioned being used. Processes are necessary -to scale to multi-core computers, not memory-sharing threads. The -fundamentals of scalable systems are fast networking and non-blocking -design—the rest is message passing. In the future, I'd like Node to -to be able to spawn new processes (probably using the <a -href="http://www.whatwg.org/specs/web-workers/current-work/">Web Workers -API</a>), but this is something that fits well into the current design. - -<h2 id="download">Download</h2> - -<p><a href="http://github.com/ry/node/tree/master">The git repo</a> - -<ul> -<li> 2009.05.31 <a href="http://s3.amazonaws.com/four.livejournal/20090531/node-0.0.2.tar.gz">node-0.0.2.tar.gz</a> -<li> 2009.05.27 <a href="http://s3.amazonaws.com/four.livejournal/20090527/node-0.0.1.tar.gz">node-0.0.1.tar.gz</a> -</ul> - - -<h2 id="build">Build</h2> - -<p>Node eventually wants to support all POSIX operating systems (including -Windows with MinGW) but at the moment it is only being tested on -<b>Linux</b>, -<b>Macintosh</b>, and -<b>FreeBSD</b>. The build system requires Python. V8, on which -Node is built, supports only IA-32 and ARM processors. V8 is included in the -Node distribution. There are no dependencies. - -<pre class="sh_none"> +puts("Server running at http://127.0.0.1:8000/");</pre> + + <p> + To run the server, put the code into a file + <code>example.js</code> and execute it with the <code>node</code> + program + </p> + <pre class="sh_none"> +% /usr/local/bin/node example.js +Server running at http://127.0.0.1:8000/</pre> + + <p> + See the <a href="api.html">API documentation</a> for more + examples. + </p> + + <h2 id="audience">Audience</h2> + + <p>This project is for those interested in</p> + <ul> + <li>server-side javascript</li> + <li>developing evented servers</li> + <li>developing new web frameworks</li> + </ul> + + <h2 id="about">About</h2> + + <p> + Node's goal is to provide an easy way to build scalable network + programs. In the above example, the 2 second delay does not + prevent the server from handling new requests. Node tells the + operating system (through <code>epoll</code>, <code>kqueue</code>, + <code class="sh_none">/dev/poll</code>, or <code>select</code>) + that it should be notified when the 2 seconds are up or if a new + connection is made—then it goes to sleep. If someone new + connects, then it executes the callback, if the timeout expires, + it executes the inner callback. Each connection is only a small + heap allocation. + </p> + + <p> + This is in contrast to today's more common model where OS threads + are employed for concurrency. Thread-based networking + <a href="http://www.sics.se/~joe/apachevsyaws.html">is</a> + <a href="http://www.kegel.com/c10k.html">relatively</a> + <a href="http://bulk.fefe.de/scalable-networking.pdf">inefficient</a> + <!-- TODO needs links --> + and very difficult to use. + + Node will show much better memory efficiency under high-loads + <!-- TODO benchmark --> + than systems which allocate 2mb thread stacks for each connection. + + Furthermore, users of Node are free from worries of dead-locking + the process—there are no locks. No function in Node + directly performs I/O, so the process never blocks. Because + nothing blocks, less-than-expert programmers are able to develop + fast systems. + </p> + + <p> + Node is similar in design to systems like Ruby's + <a href="http://rubyeventmachine.com/">Event Machine</a> + or Python's <a href="http://twistedmatrix.com/">Twisted</a>. + Node takes the event model a bit further. For example, in other + systems there is always a blocking call to start the event-loop. + Typically one defines behavior through callbacks at the beginning + of a script and at the end starts a server through a call like + <code>EventMachine::run()</code>. In Node it works differently. + By default Node enters the event loop after executing the input + script. Node exits the event loop when there are no more callbacks + to perform. Like in traditional browser javascript, the event loop + is hidden from the user. + </p> + + <p> + Node's HTTP API has grown out of my difficulties developing and + working with web servers. For example, streaming data through + most web frameworks is impossible. Or the oft-made false + assumption that all message headers have unique fields. Node + attempts to correct these and other problems in its API. Coupled + with Node's purely evented infrastructure, it will make a more + comprehensive foundation for future web libraries/frameworks. + </p> + + <p> + <i> + But what about multiple-processor concurrency? Threads are + necessary to scale programs to multi-core computers. + </i> + The name <i>Node</i> should give some hint at how it is envisioned + being used. Processes are necessary to scale to multi-core + computers, not memory-sharing threads. The fundamentals of scalable + systems are fast networking and non-blocking design—the rest + is message passing. In the future, I'd like Node to to be able to + spawn new processes (probably using the + <a href="http://www.whatwg.org/specs/web-workers/current-work/"> + Web Workers API + </a>), but this is something that fits well into the current design. + </p> + + <h2 id="download">Download</h2> + + <p> + <a href="http://github.com/ry/node/tree/master">The git repo</a> + </p> + <ul> + <li> + 2009.05.31 + <a href="http://s3.amazonaws.com/four.livejournal/20090531/node-0.0.2.tar.gz">node-0.0.2.tar.gz</a> + </li> + <li> + 2009.05.27 + <a href="http://s3.amazonaws.com/four.livejournal/20090527/node-0.0.1.tar.gz">node-0.0.1.tar.gz</a> + </li> + </ul> + + <h2 id="build">Build</h2> + + <p> + Node eventually wants to support all POSIX operating systems + (including Windows with MinGW) but at the moment it is only being + tested on <b>Linux</b>, <b>Macintosh</b>, and <b>FreeBSD</b>. The + build system requires Python. V8, on which Node is built, + supports only IA-32 and ARM processors. V8 is included in the Node + distribution. There are no dependencies. + </p> + + <pre class="sh_none"> ./configure make -make install -</pre> +make install</pre> -<p> Then have a look at the <a href="api.html">API documentation</a>. + <p> + Then have a look at the <a href="api.html">API documentation</a>. + </p> -<p>To run the tests + <p>To run the tests</p> -<pre class="sh_none"> + <pre class="sh_none"> ./configure --debug -make test -</pre> +make test</pre> -<h2 id="community">Community</h2> + <h2 id="community">Community</h2> -<p> - For help and discussion subscribe to the mailing list at - <a href="http://groups.google.com/group/nodejs">http://groups.google.com/group/nodejs</a> - or send an email to <a href="mailto:nodejs+subscribe@googlegroups.com">nodejs+subscribe@googlegroups.com</a>. -</p> - -</body> + <p> + For help and discussion subscribe to the mailing list at + <a href="http://groups.google.com/group/nodejs">http://groups.google.com/group/nodejs</a> + or send an email to <a href="mailto:nodejs+subscribe@googlegroups.com">nodejs+subscribe@googlegroups.com</a>. + </p> + </div> + </body> </html> |