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. +
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. +
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 thestringand a trailing new-line tostdout. -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. -
Timers
- --
-
setTimeout(callback, delay)
- - To schedule execution of
callbackafterdelay- milliseconds. Returns atimeoutIdfor possible use with -clearTimeout(). - - clearTimeout(timeoutId)
- - Prevents said timeout from triggering. - -
setInterval(callback, delay)
- - To schedule the repeated execution of
callbackevery -delaymilliseconds. Returns aintervalIdfor - possible use withclearInterval(). - - 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+ 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 +
+ +Fileobject. +POSIX Wrappers
+ ++ All POSIX wrappers have a similar form. They return +
+undefinedand have a callback called +on_completionas their last argument. The +on_completioncallback 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 -
++ 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 thatstat()is executed before the -rename(). The correct way to do this, is use the -on_completioncallback forrename()-+});++ because it could be that
+stat()is executed before + therename(). The correct way to do this, is use the +on_completioncallback forrename()+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.rename(path1, path2, on_completion(status))
+ - rename(2) -
node.fs.open(path, flags, mode, on_completion(status, fd))
- - open(2)
-
The constants like
O_CREATare defined at -node.constants.O_CREAT. -
+ node.fs.stat(path, on_completion(status, stats))
+ - stat(2) -
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. Ifnull, the data - will be written at the current position. + 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.read(fd, length, position, encoding, on_completion(status, data))
- - Read data from the file specified by
fd. + node.fs.open(path, flags, mode, on_completion(status, fd))
+ -
+ open(2)
+
+ The constants like
+O_CREATare defined at +node.constants.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. ++
-lengthis an integer specifying the number of + bytes to read. +positionis an integer specifying where to begin reading - from in the file. ++
-positionis an integer specifying where to begin + reading from in the file. +encodingis eithernode.constants.UTF8or -node.constants.RAW. - -
-
+
See also pwrite(2) +
+ encoding is either node.constants.UTF8
+ or node.constants.RAW.
+
node.fs.File
+ node.fs.File
-Easy buffered file object. +
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: +
+ 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"); ++ Request queues are local to a single file. If one does +
++fileA.write("hello"); fileB.write("world");-it could be thatfileBgets written to beforefileA-is written to. -If a certain operation order is needed involving multiple files, use the -completion callbacks: -fileA.write("hello", function () { ++ it could be that
+fileBgets written to before +fileAis 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
-+
-
+
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) { @@ -253,48 +316,52 @@ file.onError = function (method, errno, msg) { 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.ServerHere is an example of a echo server which listens for connections on port -7000 -
+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 () {
@@ -309,280 +376,331 @@ function Echo (socket) {
};
}
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.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
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). - - -
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().datawill - 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.
-
onReceivewill not be called after this. - After receiving thisreadyStatewill be"writeOnly". - You should probably just callconnection.close()in this - callback. - - conneciton.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.) -
+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. +
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
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.) +
- conneciton.onError = function () { };
- - Called on an error. -
connection.onError = function () { };
+ - Called on an error. +
-
+
node.tcp.Connection
+
+
+ This object is used as a TCP client and also as a server-side
+ socket for node.tcp.Servers.
+
-
+
node.http
+ 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. +
+ 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 -
+++ 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
Cookielines. +]
+ 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.
-
+node.http.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. +
+
- new node.http.Server(request_handler, options);
- -
-
Creates a new web server. +
server.close()
+ -
+
Stops the server from accepting new connections.
+
+ 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. -
-
-
-
- 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.
-
-
-
-
node.http.ServerRequest
-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.params-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:
-
+
+ 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_handlercallback. +-
+
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.params
+ -
+
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
-
onBodyCompleteis executedonBodywill no longer be called. -
-
- req.setBodyEncoding(encoding)
- -
- Set the encoding for the request body. Either
"utf8"or -"raw". Defaults to raw. -
- -node.http.ServerResponseThis 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_handlercallback. - - --
-
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: -
+};
+ 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
onBodyCompleteis executed +onBodywill 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_handlercallback. +-
+
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 - beforeres.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 theencodingis -"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.ClientAn 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-+ ]);
++ 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". +
+
+ 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) {
@@ -592,135 +710,162 @@ req.finish(function (res) {
res.onBody = function (chunk) {
puts("BODY: " + chunk);
};
-});
-
-
--
-
new node.http.Client(port, host);
- - Constructs a new HTTP client.
portandhost-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.
+});
+
+
-
+
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. ++ 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-
request_headersis optional. -request_headersshould be an array of 2-element arrays. - Additional request headers might be added internally by Node. - Returns aClientRequestobject. - -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 withreq.sendBody().) - -GETand -HEADrequests 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 when -chunkis 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. - Theresponse_handlercallback is executed with one argument: a -ClientResponseobject. -
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:
-
-
+ 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");
function onLoad () {
assertEquals(1, 2);
-}
-
-The contents of mjsunit.js:
+}
+
The contents of mjsunit.js:
++function fail (expected, found, name_opt) { // ... } @@ -731,41 +876,54 @@ exports.assertEquals = function (expected, found, name_opt) { if (!deepEquals(found, expected)) { fail(expected, found, name_opt); } -}; -- -The module
mjsunithas exported a function -assertEquals().mjsunit.jsmust be in the -same directory asfoo.jsforinclude()to find it. -The module path is relative to the file callinginclude(). -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
onLoadcan be set and will notify the user -when the included modules are loaded. Each file/module can have anonLoadcallback. - -To export an object, add to the special
exportsobject. -The functionsfailanddeepEqualsare not -exported and remain private to the module. - -
require()is likeinclude()except does not -polute the global namespace. It returns a namespace object. The exported objects -can only be guaranteed to exist after theonLoad()callback is -made. For example: -+};+ ++ The module
+ +mjsunithas exported a function +assertEquals().mjsunit.jsmust be + in the same directory asfoo.jsfor +include()to find it. The module path is relative + to the file callinginclude(). 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 +
+ +onLoadcan be set and will notify the user when the + included modules are loaded. Each file/module can have an +onLoadcallback. ++ To export an object, add to the special
+ +exports+ object. The functionsfailand +deepEqualsare not exported and remain private to + the module. ++
+require()is likeinclude()except + does not polute the global namespace. It returns a namespace + object. The exported objects can only be guaranteed to exist + after theonLoad()callback is made. For example: +var mjsunit = require("mjsunit"); function onLoad () { mjsunit.assertEquals(1, 2); -} -- -
include()andrequire()cannot be used after -onLoad()is called. So put them at the beginning of your file. +}
+ include() and require() cannot be
+ used after onLoad() is called. So put them at the
+ beginning of your file.
+