+ +

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

`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 d80d5b5..cddf99c 100644 --- a/website/index.html +++ b/website/index.html @@ -1,124 +1,20 @@ - + node.js

Benchmarks
Download
Build
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 -
-

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

`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 0000000..d7bd929 --- /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; +} + -- 2.7.4