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.
ARGV: An array containing the command line arguments.
stdout, - stderr, and - stdin -: Objects of type node.fs.File. (See below)

- -

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 - everydelay milliseconds. Returns a - intervalId for possible use with - clearInterval(). -
clearInterval(intervalId): Stops a interval from triggering.

- -

Processes and IPC

- -

- Node provides a tridirectional popen(3) facility. - It is possible to stream data through the child's stdin, - stdout, and stderr in a fully non-blocking - way. -

- -

new node.Process(command)

Launches a new process with the given command. For example: -

var ls = new Process("ls -lh /usr");

process.pid

The PID of the child process.

process.onOutput = function (chunk) { };

A callback to receive output from the process's stdout. - At the moment the received data is always a string and utf8 encoded. - (More encodings will be supported in the future.) - -

If the process closes its stdout, this callback will - be issued with null as an argument. Be prepared for this - possibility. -

process.onError = function (chunk) { };

A callback to receive output from the process's stderr. - At the moment the received data is always a string and utf8 encoded. - (More encodings will be supported in the future.) - -

If the process closes its stderr, this callback will - be issued with null as an argument. Be prepared for this - possibility. -

process.onExit = function (exit_code) { };

A callback which is called when the child process terminates. - The argument is the exit status of the child. -

process.write(data, encoding="ascii");

Write data to the child process's stdin. The second - argument is optional and specifies the encoding: possible values are - "utf8", "ascii", and "raw". -

process.close();

Closes the process's stdin stream.

process.kill(signal=node.SIGTERM);

Kills the child process with the given signal. If no argument is - given, the process will be sent node.SIGTERM. The standard - POSIX signals are defined under the node namespace (e.g. - node.SIGINT, node.SIGUSR1). -

- -

`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.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.connect(port, host="127.0.0.1"): - Opens a connection to the specified port and - host. If the second parameter is omitted, localhost is - assumed. -
connection.remoteAddress: - The string representation of the remote IP address. For example, - "74.125.127.100" or "2001:4860:a005::68". - -
This member is only present in server-side connections.
-
connection.readyState: - Either "closed", "open", "opening" - "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). -
connection.onConnect = function () { };: Call once the connection is established.
connection.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. -
connection.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. -
connection.onDisconnect = function (had_error) { };: - Called once the connection is fully disconnected. - -
- The callback is passed one boolean argument had_error. - This lets one know if the connect was closed due to an error. - (TODO: look up error codes.) -
-
connection.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's HTTP abstraction deals with connection handling and message - parsing only. It parses the message into headers and body - but it does - not parse any of the headers or the body. This is left to the user. That - means, for example, that Node does not (and will never) provide API - to access or manipulate Cookies or multi-part bodies. -

- -

`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. This contains only the parameters that are - present in the actual http request. That is, if the request is -

GET /status?name=ryan HTTP/1.1\r\n
-Accept: */*\r\n
-\r\n
-

- Then req.uri will be -

-{ path: "/status", 
-  file: "status", 
-  directory: "/", 
-  params: { "name" : "ryan" } 
-}

- In particular, note that req.uri.protocol is - undefined. This is because there was no URI protocol given - in the actual HTTP Request. -

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

req.uri.toString(), req.uri.source

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 = function (chunk) { };

- 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 = function () { };

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

req.interrupt()

- Interrupt the request. You will not receive anymore callbacks. - This is useful if, for example someone is streaming up a file but it - is too large and neesd to be stopped. The connection to the client - will be closed immediately. -

- -

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

- -

- Note: This is the raw HTTP body and has nothing to do with - higher-level multi-part body encodings that may be used. -

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

- -

- Do remember to include the Content-Length header if you - plan on sending a body. If you plan on streaming the body, perhaps - set Transfer-Encoding: chunked. -

- -

- 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.js");
-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);
-  }
-};

- -

- The module mjsunit.js has exported a 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(). -

- -

Alternatively one can use HTTP URLs to load modules. For example, - -

include("http://tinyclouds.org/node/mjsunit.js");

- -

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

- -

`onLoad`

- -

- Because module loading does not happen instantaneously, and - because Node has a policy of never blocking, a callback - onLoad can be set that will notify the user when 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. - - Alternatively, one can use this instead of - exports. -

- -

- 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.js");
-function onLoad () {
-  mjsunit.assertEquals(1, 2);
-}

- -

- include() and require() cannot be - used after onLoad() is called. -

- -

`onExit`

- -

- When the program exits a callback onExit() will be - called for each module (children first). -

- -

- The onExit() callback cannot perform I/O as the process is - going to forcably exit in several microseconds, however it is a good - hook to perform some constant time checks of the module's state. - It's useful for unit tests. -

- -

-include("mjsunit.js");
-
-var timer_executed = false;
-
-setTimeout(function () {
-  timer_executed = true
-}, 1000);
-
-function onExit () {
-  assertTrue(timer_executed);
-}
-

- -

- Just to reiterate: onExit(), is not the place to close - files or shutdown servers. The process will exit before they get - performed. -

- -