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 -stringand a trailing new-line to -stdout. - -- The
-callbackargument 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 pipingstdoutinto an - NFS file,printf()will block from network latency. - There is an internal queue forputs()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
callbackafter -delaymilliseconds. Returns atimeoutId- for possible use withclearTimeout(). -
-
- clearTimeout(timeoutId)
- - Prevents said timeout from triggering. - -
setInterval(callback, delay)
- -
- To schedule the repeated execution of
callback- everydelaymilliseconds. Returns a -intervalIdfor 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 withnullas 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 withnullas 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
stdinstream.
-
- 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 thenodenamespace (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_CREATare defined at -node.O_CREAT. -
-
- node.fs.write(fd, data, position, on_completion(status, written))
- -
- Write data to the file specified by
fd. --
-datais either an array of integer (for raw - data) or a string for UTF-8 encoded characters. --
-positionrefers 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. - --
- -lengthis an integer specifying the number of - bytes to read. --
- -positionis an integer specifying where to begin - reading from in the file. --
-encodingis eithernode.UTF8- ornode.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
-optionsargument is optional. It can contain - the following fields --
-
fd— a file descriptor for the file.
- -
-
encoding— howfile.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. --
-modeis 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_completionis a callback that is made - without arguments when the operation completes. It is optional. - If an error occurred theon_completioncallback - will not be called, but thefile.onErrorwill 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_handleris a callback which is called - on each connection. It is given one argument: an instance of -node.tcp.Connection. --
-optionsfor now only supports one option: -backlogwhich should be an integer and describes - how large of a connection backlog the operating system should - maintain for this server. Thebacklogdefaults - to 1024. -
-
- server.listen(port, host=null)
- -
- Tells the server to listen for TCP connections to
port- andhost. Note,hostis optional. If -hostis 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
portand -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
readyStatewill 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(). -datawill 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.
-
onReceivewill not be called after this. After - receiving thisreadyStatewill 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
- -optionsargument is optional. The -optionsargument accepts the same values as the - options argument fornode.tcp.Serverdoes. -- The
-request_handleris a callback which is made - on each request with aServerRequestand -ServerResponsearguments. -
-
- 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 -
- Thenreq.uriwill be --{ path: "/status", - file: "status", - directory: "/", - params: { "name" : "ryan" } -}- In particular, note thatreq.uri.protocolis -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
onBodyCompleteis executed -onBodywill 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
sendHeaderwas - called. It sends a chunk of the response body. This method may - be called multiple times to provide successive parts of the body. - -- If
- -chunkis a string, the second parameter - specifies how to encode it into a byte stream. By default the -encodingis"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.
portand -hostrefer 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_headersis optional. -request_headersshould be an array of 2-element - arrays. Additional request headers might be added internally - by Node. Returns aClientRequestobject. -- Do remember to include the
- -Content-Lengthheader if you - plan on sending a body. If you plan on streaming the body, perhaps - setTransfer-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().) --
-GETandHEADrequests 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
- -chunkargument should be an array of integers - or a string. -- The
-encodingargument is optional and only - applies whenchunkis 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_handleris a user-supplied - callback which will be executed exactly once when the server - response headers have been received. The -response_handlercallback is executed with one - argument: aClientResponseobject. -
-
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
-Stringin the case of - UTF-8 encoding or an array of numbers in the case of raw - encoding. The body encoding is set withres.setBodyEncoding(). -
-
- res.onBodyComplete
- -
- Callback. Made exactly once for each message. No arguments.
- After
onBodyCompleteis executed -onBodywill 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.
-