diff --git a/website/api.html b/website/api.html new file mode 100644 index 0000000000..a87f721b3b --- /dev/null +++ b/website/api.html @@ -0,0 +1,768 @@ + + + + + + + +node.js + +
+
    +
  1. Timers +
  2. File I/O +
      +
    1. Wrappers +
    2. File +
    +
  3. TCP +
      +
    1. Server +
    2. Connection +
    +
  4. HTTP +
      +
    1. Server +
        +
      1. Request +
      2. Response +
      +
    2. Client +
        +
      1. Request +
      2. Response +
      +
    +
  5. Modules +
+
+
+ +

Node API

+ +

Conventions: Callbacks are object members which are prefixed with +on. All methods and members are camel cased. Constructors +always have a capital first letter. + +

+Node supports 3 byte-string encodings: +ASCII ("ascii"), +UTF-8 ("utf8"), and +raw binary ("raw"). +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 V8 supports Blob objects. + +

The following are global functions:

+ +
+
puts(string, callback)
+
+ Alias for stdout.puts(). + + Outputs the string and a trailing new-line to stdout. +

The callback argument is optional and mostly useless: it will + notify the user when the operation has completed. Everything in node is + asynchronous; puts() is no exception. This might seem ridiculous + but, if for example, one is piping stdout into an NFS file, + printf() will block from network latency. + There is an internal queue for puts() output, so you can be assured that + output will be displayed in the order it was called. +

+ +
print(string, callback)
+
Like puts() but without the trailing new-line.
+ +
node.debug(string)
+
A synchronous output function. Will block the process and output the + string immediately to stdout. Use with care.
+ +
node.exit(code)
+
Immediately ends the process with the specified code.
+
+ +

Timers

+ +
+
setTimeout(callback, delay)
+
To schedule execution of callback after delay + milliseconds. Returns a timeoutId for possible use with + clearTimeout(). + +
clearTimeout(timeoutId)
+
Prevents said timeout from triggering. + +
setInterval(callback, delay)
+
To schedule the repeated execution of callback every + delay milliseconds. Returns a intervalId for + possible use with clearInterval(). + +
clearInterval(intervalId)
+
Stops a interval from triggering.
+
+ +

node.fs

+ +

File I/O is tricky because there are not simple non-blocking ways to do it. +Node handles file I/O by employing an internal thread +pool +to execute file system calls. + +

This part of the API is split into two parts: simple wrappers around +standard POSIX file I/O functions and a user-friendly File +object. + +

POSIX Wrappers

+ +

All POSIX wrappers have a similar form. They return +undefined and have a callback called on_completion +as their last argument. The on_completion 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: +

+node.fs.unlink("/tmp/hello", function (status) {
+  if (status == 0) 
+    puts("successfully deleted /tmp/hello");
+});
+
+ +

There is no guaranteed ordering to the POSIX wrappers. The following is +very much prone to error +

+node.fs.rename("/tmp/hello", "/tmp/world");
+node.fs.stat("/tmp/world", function (status, stats) {
+  puts("stats: " + JSON.stringify(stats));
+});
+
+because it could be that stat() is executed before the +rename(). The correct way to do this, is use the +on_completion callback for rename() +
+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));
+  });
+});
+
+ +
+
node.fs.rename(path1, path2, on_completion(status))
+
rename(2)
+ +
node.fs.stat(path, on_completion(status, stats))
+
stat(2)
+ +
node.fs.unlink(path, on_completion(status))
+
unlink(2)
+ +
node.fs.rmdir(path, on_completion(status))
+
rmdir(2)
+ +
node.fs.close(fd, on_completion(status))
+
close(2)
+ +
node.fs.open(path, flags, mode, on_completion(status, fd))
+
open(2) +

The constants like O_CREAT are defined at + node.constants.O_CREAT. +

+ +
node.fs.write(fd, data, position, on_completion(status, written))
+
Write data to the file specified by fd. +

data is either an array of integer (for raw data) or a string + for UTF-8 encoded characters. +

position refers to the offset from the beginning of the + file where this data should be written. If null, the data + will be written at the current position. + +

See also pwrite(2) + +

+ +
node.fs.read(fd, length, position, encoding, on_completion(status, data))
+
Read data from the file specified by fd. + +

length is an integer specifying the number of bytes to read. + +

position is an integer specifying where to begin reading + from in the file. + +

encoding is either node.constants.UTF8 or + node.constants.RAW. + +

+ +

node.fs.File

+ +

Easy buffered file object. + +

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: + +

+var file = new node.fs.File();
+file.open("/tmp/blah", "w+");
+file.write("hello");
+file.write("world");
+file.close();
+ +

+Request queues are local to a single file. +If one does +

fileA.write("hello");
+fileB.write("world");
+it could be that fileB gets written to before fileA +is written to. +If a certain operation order is needed involving multiple files, use the +completion callbacks: +
fileA.write("hello", function () {
+  fileB.write("world");
+});
+ +
+
new node.fs.File(options={})
+
Creates a new file object. + +

The options argument is optional. It can contain the + following fields +

    +
  • fd — a file descriptor for the file. +
  • encoding — how file.read() should return + data. Either "raw" or "utf8". Defaults to raw. +
+
+ + +
file.onError = function (method, errno, msg) { }
+
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. + +

Example

+
+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+")
+
+ +
file.open(path, mode, on_completion())
+
Opens the file at path. +

mode is a string: + "r" open for reading and writing. + "r+" open for only reading. + "w" create a new file for reading and writing; if it + already exists truncate it. + "w+" create a new file for writing only; if it already + exists truncate it. + "a" create a new file for writing and reading. Writes + append to the end of the file. + "a+" +

The on_completion is a callback that is made without + arguments when the operation completes. It is optional. + If an error occurred the on_completion callback will not be + called, but the file.onError will be called. +

+ +
file.read(length, position, on_completion(data))
+
+
+ +
file.write(data, position, on_completion(written))
+
+
+ +
file.close(on_completion())
+
+
+
+ + +

node.tcp

+ +

node.tcp.Server

+ +

Here is an example of a echo server which listens for connections on port +7000 +

+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");
+
+ +
+
new node.tcp.Server(connection_handler(socket), options={});
+
Creates a new TCP server. + +

connection_handler is a callback which is called + on each connection. It is given one argument: an instance of + node.tcp.Connection. + +

options for now only supports one option: + backlog which should be an integer and describes how large of + a connection backlog the operating system should maintain for this server. + The backlog defaults to 1024. +

+ +
server.listen(port, host=null)
+
Tells the server to listen for TCP connections to port + and host. Note, host is optional. If + host is not specified the server will accept connections to + any IP address on the specified port. +
+ +
server.close()
+
Stops the server from accepting new connections.
+
+ + +

node.tcp.Connection

+ +

This object is used as a TCP client and also as a server-side socket for +node.tcp.Servers. + +

+
new node.tcp.Connection()
+
Creates a new connection object. +
+ +
connection.readyState
+
Either "closed", "open", + "readOnly", or "writeOnly". +
+ +
connection.setEncoding(encoding)
+
Sets the encoding (either "utf8" or "raw") + for data that is received. +
+ +
connection.send(data, encoding="ascii")
+
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. +
+ +
connection.close()
+
Half-closes the connection. I.E. sends a FIN packet. It is possible + the server will still send some data. + After calling this readyState will be "readOnly". +
+ +
connection.fullClose()
+
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 + close(). +
+ +
connection.forceClose()
+
Ensures that no more I/O activity happens on this socket. + Only necessary in case of errors (parse error or so). +
+ +
conneciton.onConnect = function () { };
+
Call once the connection is established.
+ +
conneciton.onReceive = function (data) { };
+
Called when data is received on the connection. Encoding of data is + set by connection.setEncoding(). data will + either be a string, in the case of utf8, or an array of integer in the + case of raw encoding.
+ +
conneciton.onEOF = function () { };
+
Called when the other end of the connection sends a FIN packet. + onReceive will not be called after this. + After receiving this readyState will be "writeOnly". + You should probably just call connection.close() in this + callback. + +
conneciton.onDisconnect = function () { };
+
Called once the connection is fully disconnected.
+ +
conneciton.onError = function () { };
+
Called on an error.
+
+ +

node.http

+ +

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. + +

HTTP message headers are represented by an array of 2-element arrays like this +

+[ ["Content-Length", "123"]
+, ["Content-Type", "text/plain"]
+, ["Connection", "keep-alive"]
+, ["Accept", "*/*"]
+]
+
+

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 Cookie lines. + +

node.http.Server

+ +
+
new node.http.Server(request_handler, options);
+
+

Creates a new web server. + +

+ The options argument is optional. + The options argument accepts the same values + as the options argument for node.tcp.Server does. + +

The request_handler is a + callback which is made on each request with a + ServerRequest and + ServerResponse arguments. + +

+ +
server.listen(port, hostname) +
+

Begin accepting connections on the specified port and hostname. If the + hostname is omitted, the server will accept connections directed to any + address. +

+ +
server.close() +
+

Stops the server from accepting new connections. +

+
+ + +

node.http.ServerRequest

+ +

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 request_handler callback. + +

+
req.method +
The request method as a string. Read only. Example: "GET", + "DELETE".
+ +
req.uri +
Request URI. (Object.) +
req.uri.anchor +
req.uri.query +
req.uri.file +
req.uri.directory +
req.uri.path +
req.uri.relative +
req.uri.port +
req.uri.host +
req.uri.password +
req.uri.user +
req.uri.authority +
req.uri.protocol +
req.uri.queryKey +
req.uri.toString(), req.uri.source +
The original URI found in the status line. + +
req.headers +
The request headers expressed as an array of 2-element arrays. Read only. + +
req.httpVersion
+
The HTTP protocol version as a string. Read only. Examples: "1.1", + "1.0" + +
req.onBody
+
Callback. Should be set by the user to be informed of when a piece + of the message body is received. Example: +
+req.onBody = function (chunk) {
+  puts("part of the body: " + chunk);
+};
+
+ A chunk of the body is given as the single argument. The transfer-encoding + has been decoded. + +

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 + req.setBodyEncoding(). + +

req.onBodyComplete
+
Callback. Made exactly once for each message. No arguments. After + onBodyComplete is executed onBody will no longer be called. +
+ +
req.setBodyEncoding(encoding)
+
+ Set the encoding for the request body. Either "utf8" or + "raw". Defaults to raw. +
+ +

node.http.ServerResponse

+ +

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 request_handler callback. + + +

+
res.sendHeader(statusCode, headers)
+
+ Sends a response header to the request. The status code is a 3-digit + HTTP status code, like 404. The second argument, + headers, should be an array of 2-element arrays, + representing the response headers. + +

Example: +

+var body = "hello world";
+res.sendHeader(200, [ ["Content-Length", body.length]
+                    , ["Content-Type", "text/plain"]
+                    ]);
+
+ This method must only be called once on a message and it must be called + before res.finish() is called. +
+ +
res.sendBody(chunk, encoding="ascii")
+
+ This method must be called after sendHeader was called. It + sends a chunk of the response body. This method may be called multiple + times to provide successive parts of the body. + +

If chunk is a string, the second parameter specifies how + to encode it into a byte stream. By default the encoding is + "ascii". +

+ +
res.finish()
+
+ This method signals that all of the response headers and body has been + sent; that server should consider this message complete. + The method, res.finish(), MUST be called on each response. + +
+ +

node.http.Client

+ +

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. +Currently the implementation does not pipeline requests. + +

Example of connecting to google.com +

+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);
+  };
+});
+
+ +
+
new node.http.Client(port, host);
+
Constructs a new HTTP client. port and host +refer to the server to be connected to. A connection is not established until a +request is issued. +
+ +
client.get(path, request_headers);
+
client.head(path, request_headers);
+
client.post(path, request_headers);
+
client.del(path, request_headers);
+
client.put(path, request_headers);
+
Issues a request; if necessary establishes connection. + +

+ request_headers is optional. + request_headers should be an array of 2-element arrays. + Additional request headers might be added internally by Node. + Returns a ClientRequest object. + +

Important: the request is not complete. This method only sends the +header of the request. One needs to call req.finish() 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 req.sendBody().) + +

GET and +HEAD requests normally are without bodies but HTTP does not forbid +it, so neither do we. + +

+ +

node.http.ClientRequest

+ +

This object is created internally and returned from the request methods of a +node.http.Client. It represents an in-progress request +whose header has already been sent. + +

+
req.sendBody(chunk, encoding="ascii")
+
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 ["Transfer-Encoding", +"chunked"] header line when creating the request. + +

The chunk argument should be an array of integers or a string. + +

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

req.finish(response_handler)
+ +
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 "0\r\n\r\n". + +

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

+ +

node.http.ClientResponse

+ +

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

+
res.statusCode
+
The 3-digit HTTP response status code. E.G. 404.
+ +
res.httpVersion
+
The HTTP version of the connected-to server. Probably either + "1.1" or + "1.0". +
+ +
res.headers
+
The response headers. An Array of 2-element arrays.
+ +
res.onBody
+
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. + +

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 res.setBodyEncoding(). + +

res.onBodyComplete
+
Callback. Made exactly once for each message. No arguments. After + onBodyComplete is executed + onBody will no longer be called. +
+ +
res.setBodyEncoding(encoding)
+
+ Set the encoding for the response body. Either "utf8" or + "raw". Defaults to raw. +
+
+ +

Modules

+ +

Node has a simple module loading system. In Node, files and modules are +in one-to-one correspondence. + +

As an example, +foo.js loads the module mjsunit.js. + +

The contents of foo.js: + +

+include("mjsunit");
+function onLoad () {
+  assertEquals(1, 2);
+}
+
+

The contents of mjsunit.js: + +

+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);
+  }
+};
+
+ +

Here the module mjsunit.js has exported the function +assertEquals(). mjsunit.js must be in the +same directory as foo.js for include() to find it. +The module path is relative to the file calling include(). +The module path does not include filename extensions like .js. + +

include() inserts the exported objects +from the specified module into the global namespace. + +

Because file loading does not happen instantaneously, and because Node +has a policy of never blocking, the callback onLoad can be set and will notify the user +when all the included modules are loaded. Each file/module can have an onLoad callback. + +

To export an object, add to the special exports object. + +

The functions fail and deepEquals are not +exported and remain private to the module. + +

require() is like include() except does not +polute the global namespace. It returns a namespace object. The exported objects +can only be guaranteed to exist after the onLoad() callback is +made. For example: +

+var mjsunit = require("mjsunit");
+function onLoad () {
+  mjsunit.assertEquals(1, 2);
+}
+
+ +

include() and require() cannot be used after +onLoad() is called. So put them at the beginning of your file. + + + diff --git a/website/index.html b/website/index.html index d80d5b5021..cddf99c65f 100644 --- a/website/index.html +++ b/website/index.html @@ -1,124 +1,20 @@ - + node.js

-
    -
  1. Benchmarks
    2. -
  2. Download
    3. -
  3. Build
    4. -
  4. API -
      -
    1. Timers -
    2. File I/O -
        -
      1. Wrappers -
      2. File -
      -
    3. TCP -
        -
      1. Server -
      2. Connection -
      -
    4. HTTP -
        -
      1. Server -
          -
        1. Request -
        2. Response -
        -
      2. Client -
          -
        1. Request -
        2. Response -
        -
      -
    5. Modules -
    -
    5. -

Node

-

Purely evented server-side I/O for Purely evented I/O for V8 javascript.

This is an example of a web server written with Node which responds with @@ -134,23 +30,16 @@ a:hover { text-decoration: underline; } puts("Server running at http://127.0.0.1:8000/");

To run the server, put the code into a file server.js -and call it with the node executable +and execute it with the node program 

% /usr/local/bin/node server.js
 Server running at http://127.0.0.1:8000/
-

See the API documentation for more examples. - -

Node is free to download, use, and build upon.

- - - +

See the API documentation for more examples. -

Benchmarks

+

Node is released under an MIT license.

-

TODO

Download

@@ -171,730 +60,6 @@ make make install -

API

- -

Conventions: Callbacks are object members which are prefixed with -on. All methods and members are camel cased. Constructors -always have a capital first letter. - -

-Node supports 3 byte-string encodings: -ASCII ("ascii"), -UTF-8 ("utf8"), and -raw binary ("raw"). -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 V8 supports Blob objects. - -

The following are global functions:

- -
-
puts(string, callback)
-
- Alias for stdout.puts(). - - Outputs the string and a trailing new-line to stdout. -

The callback argument is optional and mostly useless: it will - notify the user when the operation has completed. Everything in node is - asynchronous; puts() is no exception. This might seem ridiculous - but, if for example, one is piping stdout into an NFS file, - printf() will block from network latency. - There is an internal queue for puts() output, so you can be assured that - output will be displayed in the order it was called. -

- -
print(string, callback)
-
Like puts() but without the trailing new-line.
- -
node.debug(string)
-
A synchronous output function. Will block the process and output the - string immediately to stdout. Use with care.
- -
node.exit(code)
-
Immediately ends the process with the specified code.
-
- -

Timers

- -
-
setTimeout(callback, delay)
-
To schedule execution of callback after delay - milliseconds. Returns a timeoutId for possible use with - clearTimeout(). - -
clearTimeout(timeoutId)
-
Prevents said timeout from triggering. - -
setInterval(callback, delay)
-
To schedule the repeated execution of callback every - delay milliseconds. Returns a intervalId for - possible use with clearInterval(). - -
clearInterval(intervalId)
-
Stops a interval from triggering.
-
- -

node.fs

- -

File I/O is tricky because there are not simple non-blocking ways to do it. -Node handles file I/O by employing an internal thread -pool -to execute file system calls. - -

This part of the API is split into two parts: simple wrappers around -standard POSIX file I/O functions and a user-friendly File -object. - -

POSIX Wrappers

- -

All POSIX wrappers have a similar form. They return -undefined and have a callback called on_completion -as their last argument. The on_completion 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: -

-node.fs.unlink("/tmp/hello", function (status) {
-  if (status == 0) 
-    puts("successfully deleted /tmp/hello");
-});
-
- -

There is no guaranteed ordering to the POSIX wrappers. The following is -very much prone to error -

-node.fs.rename("/tmp/hello", "/tmp/world");
-node.fs.stat("/tmp/world", function (status, stats) {
-  puts("stats: " + JSON.stringify(stats));
-});
-
-because it could be that stat() is executed before the -rename(). The correct way to do this, is use the -on_completion callback for rename() -
-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));
-  });
-});
-
- -
-
node.fs.rename(path1, path2, on_completion(status))
-
rename(2)
- -
node.fs.stat(path, on_completion(status, stats))
-
stat(2)
- -
node.fs.unlink(path, on_completion(status))
-
unlink(2)
- -
node.fs.rmdir(path, on_completion(status))
-
rmdir(2)
- -
node.fs.close(fd, on_completion(status))
-
close(2)
- -
node.fs.open(path, flags, mode, on_completion(status, fd))
-
open(2) -

The constants like O_CREAT are defined at - node.constants.O_CREAT. -

- -
node.fs.write(fd, data, position, on_completion(status, written))
-
Write data to the file specified by fd. -

data is either an array of integer (for raw data) or a string - for UTF-8 encoded characters. -

position refers to the offset from the beginning of the - file where this data should be written. If null, the data - will be written at the current position. - -

See also pwrite(2) - -

- -
node.fs.read(fd, length, position, encoding, on_completion(status, data))
-
Read data from the file specified by fd. - -

length is an integer specifying the number of bytes to read. - -

position is an integer specifying where to begin reading - from in the file. - -

encoding is either node.constants.UTF8 or - node.constants.RAW. - -

- -

node.fs.File

- -

Easy buffered file object. - -

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: - -

-var file = new node.fs.File();
-file.open("/tmp/blah", "w+");
-file.write("hello");
-file.write("world");
-file.close();
- -

-Request queues are local to a single file. -If one does -

fileA.write("hello");
-fileB.write("world");
-it could be that fileB gets written to before fileA -is written to. -If a certain operation order is needed involving multiple files, use the -completion callbacks: -
fileA.write("hello", function () {
-  fileB.write("world");
-});
- -
-
new node.fs.File(options={})
-
Creates a new file object. - -

The options argument is optional. It can contain the - following fields -

    -
  • fd — a file descriptor for the file. -
  • encoding — how file.read() should return - data. Either "raw" or "utf8". Defaults to raw. -
-
- - -
file.onError = function (method, errno, msg) { }
-
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. - -

Example

-
-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+")
-
- -
file.open(path, mode, on_completion())
-
Opens the file at path. -

mode is a string: - "r" open for reading and writing. - "r+" open for only reading. - "w" create a new file for reading and writing; if it - already exists truncate it. - "w+" create a new file for writing only; if it already - exists truncate it. - "a" create a new file for writing and reading. Writes - append to the end of the file. - "a+" -

The on_completion is a callback that is made without - arguments when the operation completes. It is optional. - If an error occurred the on_completion callback will not be - called, but the file.onError will be called. -

- -
file.read(length, position, on_completion(data))
-
-
- -
file.write(data, position, on_completion(written))
-
-
- -
file.close(on_completion())
-
-
-
- - -

node.tcp

- -

node.tcp.Server

- -

Here is an example of a echo server which listens for connections on port -7000 -

-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");
-
- -
-
new node.tcp.Server(connection_handler(socket), options={});
-
Creates a new TCP server. - -

connection_handler is a callback which is called - on each connection. It is given one argument: an instance of - node.tcp.Connection. - -

options for now only supports one option: - backlog which should be an integer and describes how large of - a connection backlog the operating system should maintain for this server. - The backlog defaults to 1024. -

- -
server.listen(port, host=null)
-
Tells the server to listen for TCP connections to port - and host. Note, host is optional. If - host is not specified the server will accept connections to - any IP address on the specified port. -
- -
server.close()
-
Stops the server from accepting new connections.
-
- - -

node.tcp.Connection

- -

This object is used as a TCP client and also as a server-side socket for -node.tcp.Servers. - -

-
new node.tcp.Connection()
-
Creates a new connection object. -
- -
connection.readyState
-
Either "closed", "open", - "readOnly", or "writeOnly". -
- -
connection.setEncoding(encoding)
-
Sets the encoding (either "utf8" or "raw") - for data that is received. -
- -
connection.send(data, encoding="ascii")
-
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. -
- -
connection.close()
-
Half-closes the connection. I.E. sends a FIN packet. It is possible - the server will still send some data. - After calling this readyState will be "readOnly". -
- -
connection.fullClose()
-
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 - close(). -
- -
connection.forceClose()
-
Ensures that no more I/O activity happens on this socket. - Only necessary in case of errors (parse error or so). -
- -
conneciton.onConnect = function () { };
-
Call once the connection is established.
- -
conneciton.onReceive = function (data) { };
-
Called when data is received on the connection. Encoding of data is - set by connection.setEncoding(). data will - either be a string, in the case of utf8, or an array of integer in the - case of raw encoding.
- -
conneciton.onEOF = function () { };
-
Called when the other end of the connection sends a FIN packet. - onReceive will not be called after this. - After receiving this readyState will be "writeOnly". - You should probably just call connection.close() in this - callback. - -
conneciton.onDisconnect = function () { };
-
Called once the connection is fully disconnected.
- -
conneciton.onError = function () { };
-
Called on an error.
-
- -

node.http

- -

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. - -

HTTP message headers are represented by an array of 2-element arrays like this -

-[ ["Content-Length", "123"]
-, ["Content-Type", "text/plain"]
-, ["Connection", "keep-alive"]
-, ["Accept", "*/*"]
-]
-
-

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 Cookie lines. - -

node.http.Server

- -
-
new node.http.Server(request_handler, options);
-
-

Creates a new web server. - -

- The options argument is optional. - The options argument accepts the same values - as the options argument for node.tcp.Server does. - -

The request_handler is a - callback which is made on each request with a - ServerRequest and - ServerResponse arguments. - -

- -
server.listen(port, hostname) -
-

Begin accepting connections on the specified port and hostname. If the - hostname is omitted, the server will accept connections directed to any - address. -

- -
server.close() -
-

Stops the server from accepting new connections. -

-
- - -

node.http.ServerRequest

- -

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 request_handler callback. - -

-
req.method -
The request method as a string. Read only. Example: "GET", - "DELETE".
- -
req.uri -
Request URI. (Object.) -
req.uri.anchor -
req.uri.query -
req.uri.file -
req.uri.directory -
req.uri.path -
req.uri.relative -
req.uri.port -
req.uri.host -
req.uri.password -
req.uri.user -
req.uri.authority -
req.uri.protocol -
req.uri.queryKey -
req.uri.toString(), req.uri.source -
The original URI found in the status line. - -
req.headers -
The request headers expressed as an array of 2-element arrays. Read only. - -
req.httpVersion
-
The HTTP protocol version as a string. Read only. Examples: "1.1", - "1.0" - -
req.onBody
-
Callback. Should be set by the user to be informed of when a piece - of the message body is received. Example: -
-req.onBody = function (chunk) {
-  puts("part of the body: " + chunk);
-};
-
- A chunk of the body is given as the single argument. The transfer-encoding - has been decoded. - -

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 - req.setBodyEncoding(). - -

req.onBodyComplete
-
Callback. Made exactly once for each message. No arguments. After - onBodyComplete is executed onBody will no longer be called. -
- -
req.setBodyEncoding(encoding)
-
- Set the encoding for the request body. Either "utf8" or - "raw". Defaults to raw. -
- -

node.http.ServerResponse

- -

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 request_handler callback. - - -

-
res.sendHeader(statusCode, headers)
-
- Sends a response header to the request. The status code is a 3-digit - HTTP status code, like 404. The second argument, - headers, should be an array of 2-element arrays, - representing the response headers. - -

Example: -

-var body = "hello world";
-res.sendHeader(200, [ ["Content-Length", body.length]
-                    , ["Content-Type", "text/plain"]
-                    ]);
-
- This method must only be called once on a message and it must be called - before res.finish() is called. -
- -
res.sendBody(chunk, encoding="ascii")
-
- This method must be called after sendHeader was called. It - sends a chunk of the response body. This method may be called multiple - times to provide successive parts of the body. - -

If chunk is a string, the second parameter specifies how - to encode it into a byte stream. By default the encoding is - "ascii". -

- -
res.finish()
-
- This method signals that all of the response headers and body has been - sent; that server should consider this message complete. - The method, res.finish(), MUST be called on each response. - -
- -

node.http.Client

- -

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. -Currently the implementation does not pipeline requests. - -

Example of connecting to google.com -

-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);
-  };
-});
-
- -
-
new node.http.Client(port, host);
-
Constructs a new HTTP client. port and host -refer to the server to be connected to. A connection is not established until a -request is issued. -
- -
client.get(path, request_headers);
-
client.head(path, request_headers);
-
client.post(path, request_headers);
-
client.del(path, request_headers);
-
client.put(path, request_headers);
-
Issues a request; if necessary establishes connection. - -

- request_headers is optional. - request_headers should be an array of 2-element arrays. - Additional request headers might be added internally by Node. - Returns a ClientRequest object. - -

Important: the request is not complete. This method only sends the -header of the request. One needs to call req.finish() 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 req.sendBody().) - -

GET and -HEAD requests normally are without bodies but HTTP does not forbid -it, so neither do we. - -

- -

node.http.ClientRequest

- -

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

-
req.sendBody(chunk, encoding="ascii")
-
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 ["Transfer-Encoding", -"chunked"] header line when creating the request. - -

The chunk argument should be an array of integers or a string. - -

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

req.finish(response_handler)
- -
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 "0\r\n\r\n". - -

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

- -

node.http.ClientResponse

- -

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

-
res.statusCode
-
The 3-digit HTTP response status code. E.G. 404.
- -
res.httpVersion
-
The HTTP version of the connected-to server. Probably either - "1.1" or - "1.0". -
- -
res.headers
-
The response headers. An Array of 2-element arrays.
- -
res.onBody
-
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. - -

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 res.setBodyEncoding(). - -

res.onBodyComplete
-
Callback. Made exactly once for each message. No arguments. After - onBodyComplete is executed - onBody will no longer be called. -
- -
res.setBodyEncoding(encoding)
-
- Set the encoding for the response body. Either "utf8" or - "raw". Defaults to raw. -
-
- -

Modules

- -

Node has a simple module loading system. In Node, files and modules are -in one-to-one correspondence. - -

As an example, -foo.js loads the module mjsunit.js. - -

The contents of foo.js: - -

-include("mjsunit");
-function onLoad () {
-  assertEquals(1, 2);
-}
-
-

The contents of mjsunit.js: - -

-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);
-  }
-};
-
- -

Here the module mjsunit.js has exported the function -assertEquals(). mjsunit.js must be in the -same directory as foo.js for include() to find it. -The module path is relative to the file calling include(). -The module path does not include filename extensions like .js. - -

include() inserts the exported objects -from the specified module into the global namespace. - -

Because file loading does not happen instantaneously, and because Node -has a policy of never blocking, the callback onLoad can be set and will notify the user -when all the included modules are loaded. Each file/module can have an onLoad callback. - -

To export an object, add to the special exports object. - -

The functions fail and deepEquals are not -exported and remain private to the module. - -

require() is like include() except does not -polute the global namespace. It returns a namespace object. The exported objects -can only be guaranteed to exist after the onLoad() callback is -made. For example: -

-var mjsunit = require("mjsunit");
-function onLoad () {
-  mjsunit.assertEquals(1, 2);
-}
-
- -

include() and require() cannot be used after -onLoad() is called. So put them at the beginning of your file. diff --git a/website/style.css b/website/style.css new file mode 100644 index 0000000000..d7bd92940e --- /dev/null +++ b/website/style.css @@ -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; +} +