From 17595b5343b3eb9b75c71013e5f3f4cccadcbdfe Mon Sep 17 00:00:00 2001 From: Micheil Smith Date: Sun, 14 Nov 2010 21:12:04 +1100 Subject: [PATCH] Various changes to Net Documentation, ammended style for API. --- doc/api/_toc.markdown | 8 +- doc/api/net.markdown | 323 +++++++++++++++++++++------------------ doc/api_assets/style.css | 4 + 3 files changed, 181 insertions(+), 154 deletions(-) diff --git a/doc/api/_toc.markdown b/doc/api/_toc.markdown index 496a6118bf..e0a4bf45dc 100644 --- a/doc/api/_toc.markdown +++ b/doc/api/_toc.markdown @@ -6,14 +6,12 @@ * [Modules](modules.html) * [C/C++ Addons](addons.html) * [Process](process.html) -* [Constants](constants.html) * [Utilities](util.html) -* [FreeList](freelist.html) * [Events](events.html) * [Buffers](buffers.html) * [Streams](streams.html) * [Crypto](crypto.html) - * [Secure Streams](securepair.html) + * [Secure Streams](securepair.html) * [String Decoder](string_decoder.html) * [File System](fs.html) * [Path](path.html) @@ -29,5 +27,5 @@ * [Child Processes](child_processes.html) * [Assertion Testing](assert.html) * Appendixes - * [Appendix 1: Recommended Third-party Modules](appendix_1.html) - * [Appendix 2: Deprecated API's](appendix_2.html) + * [Appendix 1: Recommended Third-party Modules](appendix_1.html) + * [Appendix 2: Deprecated API's](appendix_2.html) diff --git a/doc/api/net.markdown b/doc/api/net.markdown index 835a8154d0..a6338b0b1b 100644 --- a/doc/api/net.markdown +++ b/doc/api/net.markdown @@ -1,4 +1,32 @@ -## net.Server +## net + +The `net` module provides you with an asynchronous network wrapper. It contains +methods for creating both servers and clients (called streams). + +### net.createServer(connectionListener) + +Creates a new TCP server. The `connectionListener` argument is +automatically set as a listener for the `'connection'` event. + +### net.createConnection(arguments...) + +Construct a new stream object and opens a stream to the given location. When +the stream is established the `'connect'` event will be emitted. + +The arguments for this method change the type of connection: + +* `net.createConnection(port, [host])` + + Creates a TCP connection to `port` on `host`. If `host` is omitted, `localhost` + will be assumed. + +* `net.createConnection(path)` + + Creates unix socket connection to `path` + +--- + +### net.Server This class is used to create a TCP or UNIX server. @@ -28,27 +56,7 @@ changed to This is an `EventEmitter` with the following events: -### Event: 'connection' - -`function (stream) {}` - -Emitted when a new connection is made. `stream` is an instance of -`net.Stream`. - -### Event: 'close' - -`function () {}` - -Emitted when the server closes. - - -### net.createServer(connectionListener) - -Creates a new TCP server. The `connectionListener` argument is -automatically set as a listener for the `'connection'` event. - - -### server.listen(port, [host], [callback]) +#### server.listen(port, [host], [callback]) Begin accepting connections on the specified `port` and `host`. If the `host` is omitted, the server will accept connections directed to any @@ -57,56 +65,50 @@ IPv4 address (`INADDR_ANY`). This function is asynchronous. The last parameter `callback` will be called when the server has been bound. - -### server.listen(path, [callback]) +#### server.listen(path, [callback]) Start a UNIX socket server listening for connections on the given `path`. This function is asynchronous. The last parameter `callback` will be called when the server has been bound. - -### server.listenFD(fd) +#### server.listenFD(fd) Start a server listening for connections on the given file descriptor. This file descriptor must have already had the `bind(2)` and `listen(2)` system calls invoked on it. -### server.close() +#### server.close() Stops the server from accepting new connections. This function is asynchronous, the server is finally closed when the server emits a `'close'` event. -### server.maxConnections +#### server.maxConnections Set this property to reject connections when the server's connection count gets high. -### server.connections +#### server.connections The number of concurrent connections on the server. +#### Event: 'connection' -## net.isIP - -### net.isIP(input) - -Tests if input is an IP address. Returns 0 for invalid strings, -returns 4 for IP version 4 addresses, and returns 6 for IP version 6 addresses. - - -### net.isIPv4(input) +`function (stream) {}` -Returns true if input is a version 4 IP address, otherwise returns false. +Emitted when a new connection is made. `stream` is an instance of +`net.Stream`. +#### Event: 'close' -### net.isIPv6(input) +`function () {}` -Returns true if input is a version 6 IP address, otherwise returns false. +Emitted when the server closes. +--- -## net.Stream +### net.Stream This object is an abstraction of of a TCP or UNIX socket. `net.Stream` instance implement a duplex stream interface. They can be created by the @@ -115,181 +117,204 @@ and passed to the user through the `'connection'` event of a server. `net.Stream` instances are EventEmitters with the following events: -### Event: 'connect' +#### stream.connect(port, [host]) +#### stream.connect(path) -`function () { }` +Opens the connection for a given stream. If `port` and `host` are given, +then the stream will be opened as a TCP stream, if `host` is omitted, +`localhost` will be assumed. If a `path` is given, the stream will be +opened as a unix socket to that path. -Emitted when a stream connection successfully is established. -See `connect()`. +Normally this method is not needed, as `net.createConnection` opens the +stream. Use this only if you are implementing a custom Stream or if a +Stream is closed and you want to reuse it to connect to another server. +This function is asynchronous. When the `'connect'` event is emitted the +stream is established. If there is a problem connecting, the `'connect'` +event will not be emitted, the `'error'` event will be emitted with +the exception. -### Event: 'secure' -`function () { }` +#### stream.setEncoding(encoding=null) -Emitted when a stream connection successfully establishes an SSL handshake with its peer. +Sets the encoding (either `'ascii'`, `'utf8'`, or `'base64'`) for data that is +received. +#### stream.setSecure([credentials]) -### Event: 'data' +Enables SSL support for the stream, with the crypto module credentials specifying +the private key and certificate of the stream, and optionally the CA certificates +for use in peer authentication. -`function (data) { }` +If the credentials hold one ore more CA certificates, then the stream will request +for the peer to submit a client certificate as part of the SSL connection handshake. +The validity and content of this can be accessed via verifyPeer() and getPeerCertificate(). -Emitted when data is received. The argument `data` will be a `Buffer` or -`String`. Encoding of data is set by `stream.setEncoding()`. -(See the section on `Readable Stream` for more information.) +#### stream.verifyPeer() -### Event: 'end' +Returns true or false depending on the validity of the peers's certificate in the +context of the defined or default list of trusted CA certificates. -`function () { }` +#### stream.getPeerCertificate() -Emitted when the other end of the stream sends a FIN packet. +Returns a JSON structure detailing the peer's certificate, containing a dictionary +with keys for the certificate 'subject', 'issuer', 'valid\_from' and 'valid\_to' -By default (`allowHalfOpen == false`) the stream will destroy its file -descriptor once it has written out its pending write queue. However, by -setting `allowHalfOpen == true` the stream will not automatically `end()` -its side allowing the user to write arbitrary amounts of data, with the -caviot that the user is required to `end()` thier side now. In the -`allowHalfOpen == true` case after `'end'` is emitted the `readyState` will -be `'writeOnly'`. +#### stream.write(data, encoding='ascii') +Sends data on the stream. The second parameter specifies the encoding in +the case of a string--it defaults to ASCII because encoding to UTF8 is rather +slow. -### Event: 'timeout' - -`function () { }` - -Emitted if the stream times out from inactivity. This is only to notify that -the stream has been idle. The user must manually close the connection. - -See also: `stream.setTimeout()` - +Returns `true` if the entire data was flushed successfully to the kernel +buffer. Returns `false` if all or part of the data was queued in user memory. +`'drain'` will be emitted when the buffer is again free. -### Event: 'drain' +#### stream.end([data], [encoding]) -`function () { }` +Half-closes the stream. I.E., it sends a FIN packet. It is possible the +server will still send some data. After calling this `readyState` will be +`'readOnly'`. -Emitted when the write buffer becomes empty. Can be used to throttle uploads. +If `data` is specified, it is equivalent to calling `stream.write(data, encoding)` +followed by `stream.end()`. -### Event: 'error' +#### stream.destroy() -`function (exception) { }` +Ensures that no more I/O activity happens on this stream. Only necessary in +case of errors (parse error or so). -Emitted when an error occurs. The `'close'` event will be called directly -following this event. +#### stream.pause() -### Event: 'close' +Pauses the reading of data. That is, `'data'` events will not be emitted. +Useful to throttle back an upload. -`function (had_error) { }` +#### stream.resume() -Emitted once the stream is fully closed. The argument `had_error` is a boolean which says if -the stream was closed due to a transmission -error. +Resumes reading after a call to `pause()`. +#### stream.setTimeout(timeout) -### net.createConnection(port, host='127.0.0.1') +Sets the stream to timeout after `timeout` milliseconds of inactivity on +the stream. By default `net.Stream` do not have a timeout. -Construct a new stream object and opens a stream to the specified `port` -and `host`. If the second parameter is omitted, localhost is assumed. +When an idle timeout is triggered the stream will receive a `'timeout'` +event but the connection will not be severed. The user must manually `end()` +or `destroy()` the stream. -When the stream is established the `'connect'` event will be emitted. +If `timeout` is 0, then the existing idle timeout is disabled. -### stream.connect(port, host='127.0.0.1') +#### stream.setNoDelay(noDelay=true) -Opens a stream to the specified `port` and `host`. `createConnection()` -also opens a stream; normally this method is not needed. Use this only if -a stream is closed and you want to reuse the object to connect to another -server. +Disables the Nagle algorithm. By default TCP connections use the Nagle +algorithm, they buffer data before sending it off. Setting `noDelay` will +immediately fire off data each time `stream.write()` is called. -This function is asynchronous. When the `'connect'` event is emitted the -stream is established. If there is a problem connecting, the `'connect'` -event will not be emitted, the `'error'` event will be emitted with -the exception. +#### stream.setKeepAlive(enable=false, [initialDelay]) +Enable/disable keep-alive functionality, and optionally set the initial +delay before the first keepalive probe is sent on an idle stream. +Set `initialDelay` (in milliseconds) to set the delay between the last +data packet received and the first keepalive probe. Setting 0 for +initialDelay will leave the value unchanged from the default +(or previous) setting. -### stream.remoteAddress +#### stream.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. -### stream.readyState +#### stream.readyState Either `'closed'`, `'open'`, `'opening'`, `'readOnly'`, or `'writeOnly'`. -### stream.setEncoding(encoding=null) +#### Event: 'connect' -Sets the encoding (either `'ascii'`, `'utf8'`, or `'base64'`) for data that is -received. +`function () { }` -### stream.setSecure([credentials]) +Emitted when a stream connection successfully is established. +See `connect()`. -Enables SSL support for the stream, with the crypto module credentials specifying the private key and certificate of the stream, and optionally the CA certificates for use in peer authentication. -If the credentials hold one ore more CA certificates, then the stream will request for the peer to submit a client certificate as part of the SSL connection handshake. The validity and content of this can be accessed via verifyPeer() and getPeerCertificate(). +#### Event: 'secure' -### stream.verifyPeer() +`function () { }` -Returns true or false depending on the validity of the peers's certificate in the context of the defined or default list of trusted CA certificates. +Emitted when a stream connection successfully establishes an SSL handshake with its peer. -### stream.getPeerCertificate() -Returns a JSON structure detailing the peer's certificate, containing a dictionary with keys for the certificate 'subject', 'issuer', 'valid\_from' and 'valid\_to' +#### Event: 'data' -### stream.write(data, encoding='ascii') +`function (data) { }` -Sends data on the stream. The second parameter specifies the encoding in -the case of a string--it defaults to ASCII because encoding to UTF8 is rather -slow. +Emitted when data is received. The argument `data` will be a `Buffer` or +`String`. Encoding of data is set by `stream.setEncoding()`. +(See the section on `Readable Stream` for more information.) -Returns `true` if the entire data was flushed successfully to the kernel -buffer. Returns `false` if all or part of the data was queued in user memory. -`'drain'` will be emitted when the buffer is again free. +#### Event: 'end' -### stream.end([data], [encoding]) +`function () { }` -Half-closes the stream. I.E., it sends a FIN packet. It is possible the -server will still send some data. After calling this `readyState` will be -`'readOnly'`. +Emitted when the other end of the stream sends a FIN packet. -If `data` is specified, it is equivalent to calling `stream.write(data, encoding)` -followed by `stream.end()`. +By default (`allowHalfOpen == false`) the stream will destroy its file +descriptor once it has written out its pending write queue. However, by +setting `allowHalfOpen == true` the stream will not automatically `end()` +its side allowing the user to write arbitrary amounts of data, with the +caveat that the user is required to `end()` their side now. In the +`allowHalfOpen == true` case after `'end'` is emitted the `readyState` will +be `'writeOnly'`. -### stream.destroy() -Ensures that no more I/O activity happens on this stream. Only necessary in -case of errors (parse error or so). +#### Event: 'timeout' -### stream.pause() +`function () { }` -Pauses the reading of data. That is, `'data'` events will not be emitted. -Useful to throttle back an upload. +Emitted if the stream times out from inactivity. This is only to notify that +the stream has been idle. The user must manually close the connection. -### stream.resume() +See also: `stream.setTimeout()` -Resumes reading after a call to `pause()`. -### stream.setTimeout(timeout) +#### Event: 'drain' -Sets the stream to timeout after `timeout` milliseconds of inactivity on -the stream. By default `net.Stream` do not have a timeout. +`function () { }` -When an idle timeout is triggered the stream will receive a `'timeout'` -event but the connection will not be severed. The user must manually `end()` -or `destroy()` the stream. +Emitted when the write buffer becomes empty. Can be used to throttle uploads. -If `timeout` is 0, then the existing idle timeout is disabled. +#### Event: 'error' -### stream.setNoDelay(noDelay=true) +`function (exception) { }` -Disables the Nagle algorithm. By default TCP connections use the Nagle -algorithm, they buffer data before sending it off. Setting `noDelay` will -immediately fire off data each time `stream.write()` is called. +Emitted when an error occurs. The `'close'` event will be called directly +following this event. -### stream.setKeepAlive(enable=false, [initialDelay]) +#### Event: 'close' + +`function (had_error) { }` + +Emitted once the stream is fully closed. The argument `had_error` is a boolean which says if +the stream was closed due to a transmission +error. + +--- + +### net.isIP + +#### net.isIP(input) + +Tests if input is an IP address. Returns 0 for invalid strings, +returns 4 for IP version 4 addresses, and returns 6 for IP version 6 addresses. + + +#### net.isIPv4(input) + +Returns true if input is a version 4 IP address, otherwise returns false. + + +#### net.isIPv6(input) + +Returns true if input is a version 6 IP address, otherwise returns false. -Enable/disable keep-alive functionality, and optionally set the initial -delay before the first keepalive probe is sent on an idle stream. -Set `initialDelay` (in milliseconds) to set the delay between the last -data packet received and the first keepalive probe. Setting 0 for -initialDelay will leave the value unchanged from the default -(or previous) setting. diff --git a/doc/api_assets/style.css b/doc/api_assets/style.css index a59bc5ee5b..dfa9cd5c28 100644 --- a/doc/api_assets/style.css +++ b/doc/api_assets/style.css @@ -115,6 +115,10 @@ h4 { margin: 2.2em 0 1.25em; } +h4 + h4 { + margin: 0 0 1.25em; +} + h5 { font-size: 1.125em; line-height: 1.4em;