From 603330a7750d59c2a1fb87e534f7049d593dddab Mon Sep 17 00:00:00 2001 From: James M Snell Date: Thu, 2 Jun 2016 20:13:09 -0700 Subject: [PATCH 1/3] doc: general improvements to net.md copy --- doc/api/net.md | 892 ++++++++++++++++++++++++++++++------------------- 1 file changed, 539 insertions(+), 353 deletions(-) diff --git a/doc/api/net.md b/doc/api/net.md index 876cf97ccfbcd3..66c06b7364f539 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -2,74 +2,133 @@ Stability: 2 - Stable -The `net` module provides you with an asynchronous network wrapper. It contains -functions for creating both servers and clients (called streams). You can include -this module with `require('net');`. +The `net` module provides an API for implementing network clients and servers. +It can be accessed using: + +```js +const net = require('net'); +``` ## Class: net.Server -This class is used to create a TCP or local server. +The `net.Server` class is used to implement TCP or local servers. -`net.Server` is an [`EventEmitter`][] with the following events: +All `net.Server` objects are [`EventEmitter`][] instances. ### Event: 'close' -Emitted when the server closes. Note that if connections exist, this -event is not emitted until all connections are ended. +The `'close'` event is emitted when the server closes. If active connections +exist, this event is not emitted until all such connections are ended. + +The listener callback is called without passing any arguments. + +```js +server.on('close', () => { + console.log('The server has been closed.'); +}); +``` ### Event: 'connection' -* {net.Socket} The connection object +The `'connection'` event is emitted when a new connection is established. -Emitted when a new connection is made. `socket` is an instance of -`net.Socket`. +The listener callback is called with the `net.Socket` object for the connection +passed as the only argument. + +```js +server.on('connection', (socket) => { + console.log('A connection has been established'); +}); +``` ### Event: 'error' -* {Error} +The `'error'` event is emitted when an error occurs. The [`'close'`][] event +will be emitted immediately following this event. + +The listener callback is called with the `Error` object passed as the only +argument. -Emitted when an error occurs. The [`'close'`][] event will be called directly -following this event. See example in discussion of `server.listen`. +```js +server.on('error', (error) => { + console.log('An error occurred!', error); +}); +``` ### Event: 'listening' -Emitted when the server has been bound after calling `server.listen`. +The `'listening'` event is emitted when the server has been bound after calling +`server.listen`. + +The listener callback is called without passing any arguments: + +```js +server.on('listening', () => { + console.log('The server is now listening for connections!'); +}); +``` ### server.address() -Returns the bound address, the address family name, and port of the server -as reported by the operating system. -Useful to find which port was assigned when getting an OS-assigned address. -Returns an object with `port`, `family`, and `address` properties: -`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }` +The `server.address()` method returns the address to which the server is +currently bound. + +If the server is bound to a network host and port, an object will be returned +with the following properties: -Example: +* `port` {number} +* `family` {String} Will be either `'IPv4'` or `'IPv6'` +* `address` {String} The IPv4 or IPv6 network address + +For example: ```js -var server = net.createServer((socket) => { - socket.end('goodbye\n'); -}).on('error', (err) => { - // handle errors here - throw err; +{ + port: 12346, + family: 'IPv4', + address: '127.0.0.1' +} +``` + +If the server is bound to a path, that path will be returned as a string. For +instance: + +```js +const net = require('net'); + +const myServer = net.createServer(); + +myServer.listen('/tmp/path', () => { + console.log(myServer.address()); + // Prints: /tmp/path }); +``` + +The `server.address()` method should not be called until after the `listening` +event has been emitted, as illustrated in the following example: + +```js +const server = net.createServer((socket) => { + socket.end('goodbye\n'); +}).on('error', (err) => throw err); // grab a random port. server.listen(() => { @@ -78,19 +137,29 @@ server.listen(() => { }); ``` -Don't call `server.address()` until the `'listening'` event has been emitted. - ### server.close([callback]) -Stops the server from accepting new connections and keeps existing -connections. This function is asynchronous, the server is finally -closed when all connections are ended and the server emits a [`'close'`][] event. -The optional `callback` will be called once the `'close'` event occurs. Unlike -that event, it will be called with an Error as its only argument if the server -was not open when it was closed. +* `callback` {Function} + +The `server.close()` method stops the server from accepting new connections +while maintaining existing connections that have not yet completed. Once the +existing connections have closed, the server will emit the [`'close'`][] +event and call the optional `callback` function (if given) with `null` passed +as the only argument. + +If `server.close()` is called while the server *is not currently listening for +new connections*, the `callback` is called with an `Error` passed as the only +argument. + +```js +server.close((err) => { + if (err) throw err; + console.log('The server is now closed!'); +}); +``` ### server.connections -Asynchronously get the number of concurrent connections on the server. Works -when sockets were sent to forks. +* `callback` {Function} + +The `server.getConnections()` method asynchronously returns the number of +concurrent connections on the server, including those held by child processes +opened using [`child_process.fork()`][]. -Callback should take two arguments `err` and `count`. +The `callback` function is invoked with two arguments: + +* `err` {Error} `null` if the operation was successful or `Error` if an + error occurred. +* `count` {number} The number of connections + +```js +server.getConnections((err, count) => { + if (err) throw err; + console.log(`There are ${count} active connections for this server.`); +}); +``` ### server.listen(handle[, backlog][, callback]) * `handle` {Object} -* `backlog` {Number} +* `backlog` {Number} Defaults to `511` * `callback` {Function} -The `handle` object can be set to either a server or socket (anything -with an underlying `_handle` member), or a `{fd: }` object. +The `server.listen()` method instructs the server to begin accepting connections +on the given `handle`. The `handle` object may either be any object with an +underlying `_handle` member (such as a `net.Socket` or another `net.Server`), +or an object with a `fd` property whose value is a numeric file descriptor +(e.g. `{fd: }`). + +It is presumed that the given `handle` has already been bound to a port or +domain socket. -This will cause the server to accept connections on the specified -handle, but it is presumed that the file descriptor or handle has -already been bound to a port or domain socket. +Passing a `handle` with a `fd` (file descriptor) is not supported on Windows. -Listening on a file descriptor is not supported on Windows. +The `server.listen()` method is asynchronous. When the server has been bound, +the [`'listening'`][] event will be emitted. -This function is asynchronous. When the server has been bound, -[`'listening'`][] event will be emitted. -The last parameter `callback` will be added as a listener for the +If a `callback` function is given, it will be added as a listener for the [`'listening'`][] event. -The parameter `backlog` behaves the same as in -[`server.listen(port[, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`]. +The `backlog` argument is the maximum size of the queue of pending connections. +The maximum possible value will be determined by the operating system through +`sysctl` settings such as `tcp_max_syn_backlog` and `somaxconn` on Linux. ### server.listen(options[, callback]) -Begin accepting connections on the specified `port` and `hostname`. If the -`hostname` is omitted, the server will accept connections on any IPv6 address -(`::`) when IPv6 is available, or any IPv4 address (`0.0.0.0`) otherwise. Use a -port value of `0` to have the operating system assign an available port. +The `server.listen()` method instructs the server to begin accepting connections +on the specified `port` and `hostname`. If the `hostname` is omitted, the server +will accept connections on any IPv6 address (`::`) when IPv6 is available, or +any IPv4 address (`0.0.0.0`) otherwise. Use a port value of `0` to have the +operating system assign an available port. -Backlog is the maximum length of the queue of pending connections. -The actual length will be determined by the OS through sysctl settings such as -`tcp_max_syn_backlog` and `somaxconn` on Linux. The default value of this -parameter is 511 (not 512). +The `backlog` argument is the maximum size of the queue of pending connections. +The maximum possible value will be determined by the operating system through +`sysctl` settings such as `tcp_max_syn_backlog` and `somaxconn` on Linux. -This function is asynchronous. When the server has been bound, -[`'listening'`][] event will be emitted. The last parameter `callback` -will be added as a listener for the [`'listening'`][] event. +The `server.listen()` method is asynchronous. When the server has been bound, +the [`'listening'`][] event will be emitted. -One issue some users run into is getting `EADDRINUSE` errors. This means that -another server is already running on the requested port. One way of handling this -would be to wait a second and then try again: +If a `callback` function is given, it will be added as a listener for the +[`'listening'`][] event. + +An `EADDRINUSE` error will occur if another server is already bound to the +requested `port`. One possible way to mitigate such errors is to wait a +second and then try again as illustrated in the following example: ```js server.on('error', (e) => { @@ -246,114 +354,128 @@ server.on('error', (e) => { }); ``` -(Note: All sockets in Node.js are set `SO_REUSEADDR`.) +*Note*: All `net.Sockets` in Node.js are set to use the `SO_REUSEADDR` flag +by default. ### server.listening -A Boolean indicating whether or not the server is listening for -connections. +A boolean indicating whether or not the server is listening for connections. ### server.maxConnections -Set this property to reject connections when the server's connection count gets -high. +The `server.maxConnections` property can be set to specify the maximum number +of connections the server will accept. Once the current number of connections +reaches this threshold, all additional connection requests will be rejected. -It is not recommended to use this option once a socket has been sent to a child -with [`child_process.fork()`][]. +*Note*: Setting this property *after* a socket has been sent to a child +using [`child_process.fork()`][] is *not recommended*. ### server.ref() -Opposite of `unref`, calling `ref` on a previously `unref`d server will *not* -let the program exit if it's the only server left (the default behavior). If -the server is `ref`d calling `ref` again will have no effect. +Calling the `server.ref()` method will cause the Node.js event loop to continue +so long as the `server` is not closed. Multiple calls to `server.ref()` will +have no effect. -Returns `server`. +Returns a reference to `server`. ### server.unref() -Calling `unref` on a server will allow the program to exit if this is the only -active server in the event system. If the server is already `unref`d calling -`unref` again will have no effect. +Calling the `server.unref()` method ensures that the Node.js event loop will +not be required to continue if this `server` is still open. Multiple calls to +`server.unref()` will have no effect. -Returns `server`. +Returns a reference to `server`. ## Class: net.Socket -This object is an abstraction of a TCP or local socket. `net.Socket` -instances implement a duplex Stream interface. They can be created by the -user and used as a client (with [`connect()`][]) or they can be created by Node.js -and passed to the user through the `'connection'` event of a server. +The `net.Socket` object is an abstraction of a TCP or local socket. All +`net.Socket` instances implement a [Duplex][] Stream interface. + +Instances may be created by users (e.g. using [`net.connect()`][]) or by +Node.js and passed to the user through the `'connection'` event. + +All `net.Socket` objects are [`EventEmitter`][] instances. ### new net.Socket([options]) -Construct a new socket object. - -`options` is an object with the following defaults: - -```js -{ - fd: null, - allowHalfOpen: false, - readable: false, - writable: false -} -``` - -`fd` allows you to specify the existing file descriptor of socket. -Set `readable` and/or `writable` to `true` to allow reads and/or writes on this -socket (NOTE: Works only when `fd` is passed). -About `allowHalfOpen`, refer to `createServer()` and `'end'` event. +* `options` {Object} + * `fd` {number} Used to specify a numeric file descriptor of an existing + socket. Defaults to `null` + * `allowHalfOpen` {boolean} If `true`, allows the socket to be in a "half + open" state. Defaults to `false` + * `readable` {boolean} If `fd` is specified, setting `readable` to `true` + allows data from the socket to be read. Defaults to `false` + * `writable` {boolean} If `fd` is specified, setting `writabl` to `true` + allows data to be written to the socket. Defaults to `false` -`net.Socket` instances are [`EventEmitter`][] with the following events: +Construct a new `net.Socket` instance. ### Event: 'close' -* `had_error` {Boolean} `true` if the socket had a transmission error. +The `'close'` event is emitted once the socket is fully closed. -Emitted once the socket is fully closed. The argument `had_error` is a boolean -which says if the socket was closed due to a transmission error. +The listener callback is called with a single boolean `had_error` argument. +If `true`, then the socket was closed due to a transmission error. + +```js +socket.on('close', (had_error) => { + if (had_error) + console.log('There was a transmission error!'); + else + console.log('The connection closed normally.'); +}); +``` ### Event: 'connect' -Emitted when a socket connection is successfully established. -See [`connect()`][]. +The `'connect'` event is emitted when a socket connection is successfully +established. See [`net.connect()`][]. + +The listener callback is called without passing any arguments. + +```js +socket.on('connect', () => { + console.log('The socket is connected!'); +}); +``` ### Event: 'data' -* {Buffer} +The `'data'` event is emitted when data is received. -Emitted when data is received. The argument `data` will be a `Buffer` or -`String`. Encoding of data is set by `socket.setEncoding()`. -(See the [Readable Stream][] section for more information.) +The listener callback will be invoked with a single `data` argument that will +be either a `Buffer` or string (if an encoding is set using +`socket.setEncoding()`). See the [Readable][] stream documentation for more +information. -Note that the __data will be lost__ if there is no listener when a `Socket` +*Note*: __Data will be lost__ if there is no listener when a `net.Socket` emits a `'data'` event. ### Event: 'drain' @@ -361,53 +483,86 @@ emits a `'data'` event. added: v0.1.90 --> -Emitted when the write buffer becomes empty. Can be used to throttle uploads. - -See also: the return values of `socket.write()` +The `'drain'` event is emitted when the `net.Socket` instances write buffer +becomes empty. This can be used to throttle writes to the socket. See the +[Writable][] stream documentation for more information. ### Event: 'end' -Emitted when the other end of the socket sends a FIN packet. +The `'end'` event is emitted when the other end of the socket sends a `FIN` +packet. + +By default (when the `allowHalfOpen` option is `false`) the socket will destroy +its underlying file descriptor once it has completely written out its pending +write queue. However, by setting `allowHalfOpen` to `true`, the socket will not +automatically end its side of the socket allowing additional data to be written. -By default (`allowHalfOpen == false`) the socket will destroy its file -descriptor once it has written out its pending write queue. However, by -setting `allowHalfOpen == true` the socket 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. +The listener callback is called without passing any arguments. + +```js +socket.on('end', () => { + console.log('The socket has ended!'); +}); +``` ### Event: 'error' -* {Error} +The `'error'` event is emitted when an error occurs. The `'close'` event will be +emitted immediately following this event. + +The listener callback is called with the `Error` passed as the only argument. -Emitted when an error occurs. The `'close'` event will be called directly -following this event. +```js +socket.on('error', (error) => { + console.log('There was an error!', error); +}); +``` ### Event: 'lookup' -Emitted after resolving the hostname but before connecting. -Not applicable to UNIX sockets. +The `'lookup'` event is emitted after the `net.Socket` has resolved the +`hostname` given when connection, but *before* the connection is established. +This event is not applicable when using UNIX sockets. + +The callback function is called with the following arguments: * `err` {Error|Null} The error object. See [`dns.lookup()`][]. * `address` {String} The IP address. * `family` {String|Null} The address type. See [`dns.lookup()`][]. * `host` {String} The hostname. +```js +socket.on('lookup', (err, address, family, host) => { + if (err) throw err; + console.log(`${host} resolved to:`, address, family); +}); +``` + ### Event: 'timeout' -Emitted if the socket times out from inactivity. This is only to notify that -the socket has been idle. The user must manually close the connection. +The `'timeout'` event is emitted if the `net.Socket` connection times out due +to inactivity. This event is only a notification that the `net.Socket` has been +idle. The user must manually close the connection. + +The listener callback is called without passing any arguments. + +```js +socket.on('timeout', () => { + console.log('There has been no activity on the connection.'); +}); +``` See also: [`socket.setTimeout()`][] @@ -416,109 +571,137 @@ See also: [`socket.setTimeout()`][] added: v0.1.90 --> -Returns the bound address, the address family name and port of the -socket as reported by the operating system. Returns an object with -three properties, e.g. -`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }` +The `socket.address()` method returns the address to which the socket is +bound, the address family name, and port of the socket as reported by the +operating system. + +The object returned has the following properties: + +* `port` {number} +* `family` {String} Either `'IPv4'` or `'IPv6'` +* `address` {String} The IPv4 or IPv6 address ### socket.bufferSize -`net.Socket` has the property that `socket.write()` always works. This is to -help users get up and running quickly. The computer cannot always keep up -with the amount of data that is written to a socket - the network connection -simply might be too slow. Node.js will internally queue up the data written to a -socket and send it out over the wire when it is possible. (Internally it is -polling on the socket's file descriptor for being writable). +The read-only `socket.bufferSize` property specifies the current amount of data +currently pending in the `net.Socket` instances write buffer. + +The `net.Socket` class has been designed such that calls to `socket.write()` +will always work so long as the connection is open. Data written to the socket +is buffered internally first, then written out to the underlying connection. If +the data is written to the buffer faster than it can be passed to the connection +(e.g. when using a slow network connection), the size of the internal buffer +can grow. -The consequence of this internal buffering is that memory may grow. This -property shows the number of characters currently buffered to be written. -(Number of characters is approximately equal to the number of bytes to be -written, but the buffer may contain strings, and the strings are lazily -encoded, so the exact number of bytes is not known.) +The value of `socket.bufferSize` represents the number of *characters* pending +in the queue. The number of characters is approximately equal to the number of +bytes, but as the internal queue is managed as `Buffer` instances that may +contain encoded strings, the exact number of bytes is not known until the +`Buffer` data is read. -Users who experience large or growing `bufferSize` should attempt to -"throttle" the data flows in their program with [`pause()`][] and [`resume()`][]. +In order to avoid large or growing `socket.bufferSize` numbers, attempts should +be made to throttle the flow of data written to the socket. ### socket.bytesRead -The amount of received bytes. +The `socket.bytesRead` property specifies the total number of bytes received. ### socket.bytesWritten -The amount of bytes sent. +The `socket.bytesWritten` property specifies the total number of bytes written. ### socket.connect(options[, connectListener]) -Opens the connection for a given socket. - -For TCP sockets, `options` argument should be an object which specifies: - - - `port`: Port the client should connect to (Required). +* `options` {Object} + * `path`: Path the client should connect to + * `port` {number} Port the client should connect to + * `host` {String} Host the client should connect to + Defaults to `'localhost'` + * `localAddress` {String} Local interface to bind to for network connections + * `localPort` {number} Local port to bind to for network connections + * `family` {number} Version of IP stack. Defaults to `4` + * `hints` {number} [`dns.lookup()` hints][]. Defaults to `0` + * `lookup` {Function} Custom lookup function. Defaults to `dns.lookup` +* `connectListener` {Function} - - `host`: Host the client should connect to. Defaults to `'localhost'`. +The `socket.connect()` method opens the connection for a given socket using +either the given `path`, or the `port` and `host`. - - `localAddress`: Local interface to bind to for network connections. +In most normal situations it is not necessary to call this method directly +as other methods such as `net.createConnection()` will call `socket.connect()` +automatically. - - `localPort`: Local port to bind to for network connections. +This method operates asynchronously. The [`'connect'`][] event is emitted when +the connection is successfully established. If an error occurs while attempting +to open the connection, the [`'error'`][] event will be emitted. - - `family` : Version of IP stack. Defaults to `4`. +If the `connectListener` argument is given, the callback will be added as a +listener for the [`'connect'`][] event. - - `hints`: [`dns.lookup()` hints][]. Defaults to `0`. - - - `lookup` : Custom lookup function. Defaults to `dns.lookup`. - -For local domain sockets, `options` argument should be an object which -specifies: +### socket.connect(path[, connectListener]) - - `path`: Path the client should connect to (Required). +* `path`: Path the client should connect to +* `connectListener` {Function} -Normally this method is not needed, as `net.createConnection` opens the -socket. Use this only if you are implementing a custom Socket. +The `socket.connect()` method opens the connection for a given socket using +the given `path`. -This function is asynchronous. When the [`'connect'`][] event is emitted the -socket is established. If there is a problem connecting, the `'connect'` event -will not be emitted, the [`'error'`][] event will be emitted with the exception. +This method operates asynchronously. The [`'connect'`][] event is emitted when +the connection is successfully established. If an error occurs while attempting +to open the connection, the [`'error'`][] event will be emitted. -The `connectListener` parameter will be added as a listener for the -[`'connect'`][] event. +If the `connectListener` argument is given, the callback will be added as a +listener for the [`'connect'`][] event. -### socket.connect(path[, connectListener]) ### socket.connect(port[, host][, connectListener]) -As [`socket.connect(options[, connectListener])`][`socket.connect(options, connectListener)`], -with options either as either `{port: port, host: host}` or `{path: path}`. +* `port` {number} Port the client should connect to +* `host` {String} Host the client should connect. to Defaults to `'localhost'` +* `connectListener` {Function} + +The `socket.connect()` method opens the connection for a given socket using +the given `port` and `host`. + +This method operates asynchronously. The [`'connect'`][] event is emitted when +the connection is successfully established. If an error occurs while attempting +to open the connection, the [`'error'`][] event will be emitted. + +If the `connectListener` argument is given, the callback will be added as a +listener for the [`'connect'`][] event. ### socket.connecting -If `true` - [`socket.connect(options[, connectListener])`][`socket.connect(options, connectListener)`] was called and -haven't yet finished. Will be set to `false` before emitting `connect` event -and/or calling [`socket.connect(options[, connectListener])`][`socket.connect(options, connectListener)`]'s callback. +A boolean property that when `true`, indicates that `socket.connect()` has been +called a connection is in the process of being established. The value will be +set to `false` once the connection is established but *before* the `'connect'` +event is emitted. The value will also be `false` before `socket.connect()` is +called. ### socket.destroy([exception]) -Ensures that no more I/O activity happens on this socket. Only necessary in -case of errors (parse error or so). +The `socket.destroy()` method ensures that no futher I/O activity can occur +with the socket. This is typically only necessary when errors occur. If `exception` is specified, an [`'error'`][] event will be emitted and any listeners for that event will receive `exception` as an argument. @@ -533,8 +716,13 @@ connection is destroyed no further data can be transferred using it. added: v0.1.90 --> -Half-closes the socket. i.e., it sends a FIN packet. It is possible the -server will still send some data. +* `data` {string|Buffer} +* `encoding` {string} A character encoding + +The `socket.end()` method causes a `FIN` packet to be sent and the [Writable][] +side of the socket to be closed. This puts to socket into a "half-closed" +state. In this state, it is possible for data to be received via the +[Readable][] side of the socket. If `data` is specified, it is equivalent to calling `socket.write(data, encoding)` followed by `socket.end()`. @@ -544,40 +732,41 @@ If `data` is specified, it is equivalent to calling added: v0.9.6 --> -The string representation of the local IP address the remote client is -connecting on. For example, if you are listening on `'0.0.0.0'` and the -client connects on `'192.168.1.1'`, the value would be `'192.168.1.1'`. +Provides the string representation of the local IP address the remote peer is +connecting on. For example, if the `net.Socket` is listening on `'0.0.0.0'` and +the peer connects on `'192.168.1.1'`, the value would be `'192.168.1.1'`. ### socket.localPort -The numeric representation of the local port. For example, -`80` or `21`. +Provides the numeric representation of the local port. For example, `80` or +`21`. ### socket.pause() -Pauses the reading of data. That is, [`'data'`][] events will not be emitted. -Useful to throttle back an upload. +The `socket.pause()` method pauses the reading of data. That is, [`'data'`][] +events will not be emitted. See the [Readable][] documentation for more +information. ### socket.ref() -Opposite of `unref`, calling `ref` on a previously `unref`d socket will *not* -let the program exit if it's the only socket left (the default behavior). If -the socket is `ref`d calling `ref` again will have no effect. +Calling the `socket.ref()` method will cause the Node.js event loop to continue +so long as the `socket` is not closed. Multiple calls to `socket.ref()` will +have no effect. -Returns `socket`. +Returns a reference to `socket`. ### socket.remoteAddress -The string representation of the remote IP address. For example, +Provides the string representation of the remote IP address. For example, `'74.125.127.100'` or `'2001:4860:a005::68'`. Value may be `undefined` if the socket is destroyed (for example, if the client disconnected). @@ -586,259 +775,270 @@ the socket is destroyed (for example, if the client disconnected). added: v0.11.14 --> -The string representation of the remote IP family. `'IPv4'` or `'IPv6'`. +Provides the string representation of the remote IP family. Will be either +`'IPv4'` or `'IPv6'`. ### socket.remotePort -The numeric representation of the remote port. For example, -`80` or `21`. +Provides the numeric representation of the remote port. For example, `80` or +`21`. ### socket.resume() -Resumes reading after a call to [`pause()`][]. +The `socket.resume()` method resumes reading after a call to +[`socket.pause()`][]. See the [Readable][] documentation for more information. ### socket.setEncoding([encoding]) -Set the encoding for the socket as a [Readable Stream][]. See -[`stream.setEncoding()`][] for more information. +The `socket.setEncoding()` method sets the encoding for the socket as a +[Readable Stream][]. See [`readable.setEncoding()`][] for more information. ### socket.setKeepAlive([enable][, initialDelay]) -Enable/disable keep-alive functionality, and optionally set the initial -delay before the first keepalive probe is sent on an idle socket. -`enable` defaults to `false`. +* `enable` {boolean} `true` to enable keep-alive, `false` to disable. Defaults + to `false`. +* `initialDelay` {number} The number of 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. Defaults to `0`. -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. Defaults to `0`. +The `socket.setKeepAlive()` method enables or disables keep-alive functionality, +and optionally sets the initial delay before the first keepalive probe is sent +on an idle socket. -Returns `socket`. +Returns a reference to `socket`. ### socket.setNoDelay([noDelay]) -Disables the Nagle algorithm. By default TCP connections use the Nagle -algorithm, they buffer data before sending it off. Setting `true` for -`noDelay` will immediately fire off data each time `socket.write()` is called. -`noDelay` defaults to `true`. +* `noDelay` {boolean} If `true`, disables Nagle's algorithm. Defaults to + `true` -Returns `socket`. +The `socket.setNoDelay()` method enables or disables Nagle's algorithm. By +default TCP connections use Nagle's algorithm and buffer data before sending +it off. Setting `true` for `noDelay` will immediately fire off data each time +`socket.write()` is called. + +Returns a reference to `socket`. ### socket.setTimeout(timeout[, callback]) -Sets the socket to timeout after `timeout` milliseconds of inactivity on -the socket. By default `net.Socket` do not have a timeout. +* `timeout` {number} +* `callback` {Function} + +The `socket.setTimeout()` method sets the socket to timeout after `timeout` +milliseconds of inactivity on the socket. By default `net.Socket` instances +do not have a timeout. -When an idle timeout is triggered the socket will receive a [`'timeout'`][] -event but the connection will not be severed. The user must manually [`end()`][] -or [`destroy()`][] the socket. +When an idle timeout is triggered, the `net.Socket` will emit a [`'timeout'`][] +event but the connection will not be severed. The user must manually +end the socket by call [`socket.end()`][] or [`socket.destroy()`][]. -If `timeout` is 0, then the existing idle timeout is disabled. +If `timeout` is `0`, then the existing idle timeout is disabled. The optional `callback` parameter will be added as a one time listener for the [`'timeout'`][] event. -Returns `socket`. +Returns a reference to `socket`. ### socket.unref() -Calling `unref` on a socket will allow the program to exit if this is the only -active socket in the event system. If the socket is already `unref`d calling -`unref` again will have no effect. +Calling the `socket.unref()` method ensures that the Node.js event loop will +not be required to continue if this `socket` is still open. Multiple calls to +`socket.unref()` will have no effect. -Returns `socket`. +Returns a reference to `socket`. ### socket.write(data[, encoding][, callback]) -Sends data on the socket. The second parameter specifies the encoding in the -case of a string--it defaults to UTF8 encoding. +* `data` {String|Buffer} The data to write +* `encoding` {String} The character encoding if `data` is a string. Defaults to + `'utf8'`. +* `callback` {Function} + +The `socket.write()` method queues data to be sent on the socket. 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. +The [`'drain'`][] event will be emitted when the buffer is again free. The optional `callback` parameter will be executed when the data is finally -written out - this may not be immediately. +written out. ## net.connect(options[, connectListener]) -A factory function, which returns a new [`net.Socket`][] and automatically -connects with the supplied `options`. +* `options` {Object} +* `connectListener` {Function} -The options are passed to both the [`net.Socket`][] constructor and the -[`socket.connect`][] method. +The `net.connect()` method creates a new [`net.Socket`][], automatically opens +the socket, then returns it. -The `connectListener` parameter will be added as a listener for the -[`'connect'`][] event once. +The `options` are passed to both the [`net.Socket`][] constructor and the +[`socket.connect`][] method. The options relevant to each may be used. -Here is an example of a client of the previously described echo server: +The `connectListener` parameter will be added as a one-time listener for the +[`'connect'`][] event. + +The following example illustrates a client for an echo server: ```js const net = require('net'); + const client = net.connect({port: 8124}, () => { // 'connect' listener console.log('connected to server!'); client.write('world!\r\n'); -}); -client.on('data', (data) => { +}).on('data', (data) => { console.log(data.toString()); client.end(); -}); -client.on('end', () => { +}).on('end', () => { console.log('disconnected from server'); }); ``` -To connect on the socket `/tmp/echo.sock` the second line would just be -changed to - -```js -const client = net.connect({path: '/tmp/echo.sock'}); -``` - ## net.connect(path[, connectListener]) -A factory function, which returns a new unix [`net.Socket`][] and automatically -connects to the supplied `path`. +* `path` {String} +* `connectListener` {Function} + +The `net.connect()` method creates a new [`net.Socket`][], automatically opens +the socket using `path`, then returns it. -The `connectListener` parameter will be added as a listener for the -[`'connect'`][] event once. +The `connectListener` parameter will be added as a one-time listener for the +[`'connect'`][] event. ## net.connect(port[, host][, connectListener]) -A factory function, which returns a new [`net.Socket`][] and automatically -connects to the supplied `port` and `host`. +* `port` {number} +* `host` {String}. Defaults to `localhost` +* `connectListener` {Function} -If `host` is omitted, `'localhost'` will be assumed. +The `net.connect()` method creates a new [`net.Socket`][], automatically opens +the socket for the given `port` and `host`, then returns it. -The `connectListener` parameter will be added as a listener for the -[`'connect'`][] event once. +The `connectListener` parameter will be added as a one-time listener for the +[`'connect'`][] event. ## net.createConnection(options[, connectListener]) -A factory function, which returns a new [`net.Socket`][] and automatically -connects with the supplied `options`. +* `options` {Object} +* `connectListener` {Function} -The options are passed to both the [`net.Socket`][] constructor and the -[`socket.connect`][] method. +The `net.createConnection()` method creates a new [`net.Socket`][], +automatically opens the socket, then returns it. -The `connectListener` parameter will be added as a listener for the -[`'connect'`][] event once. +The `options` are passed to both the [`net.Socket`][] constructor and the +[`socket.connect`][] method. The options relevant to each may be used. -Here is an example of a client of the previously described echo server: +The `connectListener` parameter will be added as a one-time listener for the +[`'connect'`][] event. + +The following example illustrates a client for an echo server: ```js const net = require('net'); + const client = net.createConnection({port: 8124}, () => { //'connect' listener console.log('connected to server!'); client.write('world!\r\n'); -}); -client.on('data', (data) => { +}).on('data', (data) => { console.log(data.toString()); client.end(); -}); -client.on('end', () => { +}).on('end', () => { console.log('disconnected from server'); }); ``` -To connect on the socket `/tmp/echo.sock` the second line would just be -changed to - -```js -const client = net.connect({path: '/tmp/echo.sock'}); -``` - ## net.createConnection(path[, connectListener]) -A factory function, which returns a new unix [`net.Socket`][] and automatically -connects to the supplied `path`. +* `path` {String} +* `connectListener` {Function} + +The `net.createConnection()` method creates a new [`net.Socket`][], +automatically opens the socket using `path`, then returns it. -The `connectListener` parameter will be added as a listener for the -[`'connect'`][] event once. +The `connectListener` parameter will be added as a one-time listener for the +[`'connect'`][] event. ## net.createConnection(port[, host][, connectListener]) -A factory function, which returns a new [`net.Socket`][] and automatically -connects to the supplied `port` and `host`. +* `port` {number} +* `host` {String}. Defaults to `localhost` +* `connectListener` {Function} -If `host` is omitted, `'localhost'` will be assumed. +The `net.createConnection()` method creates a new [`net.Socket`][], +automatically opens the socket for the given `port` and `host`, then returns it. -The `connectListener` parameter will be added as a listener for the -[`'connect'`][] event once. +The `connectListener` parameter will be added as a one-time listener for the +[`'connect'`][] event. ## net.createServer([options][, connectionListener]) -Creates a new server. The `connectionListener` argument is -automatically set as a listener for the [`'connection'`][] event. - -`options` is an object with the following defaults: - -```js -{ - allowHalfOpen: false, - pauseOnConnect: false -} -``` +* `options` {Object} + * `allowHalfOpen` {boolean} If `true`, the socket associated with each + incoming connection will not automatically send a `FIN` package when a `FIN` + packet is received from the peer. The socket becomes non-readable, but still + writable. Defaults to `false` + * `pauseOnConnect` {boolean} If `true`, the socket associated with each + incoming connection will be paused automatically and no data will be read, + allowing connections to be passed between processes without reading or + losing data. To begin reading data from a paused socket, call + `socket.resume()`. Defaults to `false` +* `connectionListener` {Function} -If `allowHalfOpen` is `true`, then the socket won't automatically send a FIN -packet when the other end of the socket sends a FIN packet. The socket becomes -non-readable, but still writable. You should call the [`end()`][] method explicitly. -See [`'end'`][] event for more information. +The `net.createServer()` method creates and returns a new `net.Server`. -If `pauseOnConnect` is `true`, then the socket associated with each incoming -connection will be paused, and no data will be read from its handle. This allows -connections to be passed between processes without any data being read by the -original process. To begin reading data from a paused socket, call [`resume()`][]. +The `connectionListener` argument is automatically set as a listener for the +[`'connection'`][] event. -Here is an example of an echo server which listens for connections -on port 8124: +The following example implements a simple echo server that listeners for +connections on port `8124`: ```js const net = require('net'); + const server = net.createServer((c) => { // 'connection' listener console.log('client connected'); @@ -847,51 +1047,33 @@ const server = net.createServer((c) => { }); c.write('hello\r\n'); c.pipe(c); -}); -server.on('error', (err) => { +}).on('error', (err) => { throw err; -}); -server.listen(8124, () => { - console.log('server bound'); -}); -``` - -Test this by using `telnet`: - -``` -telnet localhost 8124 -``` - -To listen on the socket `/tmp/echo.sock` the third line from the last would -just be changed to - -```js -server.listen('/tmp/echo.sock', () => { +}).listen(8124, () => { console.log('server bound'); }); ``` -Use `nc` to connect to a UNIX domain socket server: - -```js -nc -U /tmp/echo.sock -``` - ## 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. +* `input` {String} +The `net.isIP()` method is a simple utility for testing if `input` is an IP +address. Returns `0` for invalid strings, `4` for IPv4 addresses, and `6` for +IPv6 addresses. ## net.isIPv4(input) -Returns true if input is a version 4 IP address, otherwise returns false. +* `input` {String} + +The `net.isIPv4()` method is a simple utility that returns `true` if `input` is +a valid IPv4 address and `false` otherwise. ## net.isIPv6(input) @@ -899,7 +1081,10 @@ Returns true if input is a version 4 IP address, otherwise returns false. added: v0.3.0 --> -Returns true if input is a version 6 IP address, otherwise returns false. +* `input` {String} + +The `net.isIPv6()` method is a simple utility that returns `true` if `input` is +a valid IPv6 address and `false` otherwise. [`'close'`]: #net_event_close [`'connect'`]: #net_event_connect @@ -911,19 +1096,20 @@ Returns true if input is a version 6 IP address, otherwise returns false. [`'listening'`]: #net_event_listening [`'timeout'`]: #net_event_timeout [`child_process.fork()`]: child_process.html#child_process_child_process_fork_modulepath_args_options -[`connect()`]: #net_socket_connect_options_connectlistener -[`destroy()`]: #net_socket_destroy +[`net.connect()`]: #net_socket_connect_options_connectlistener +[`socket.destroy()`]: #net_socket_destroy [`dns.lookup()`]: dns.html#dns_dns_lookup_hostname_options_callback [`dns.lookup()` hints]: dns.html#dns_supported_getaddrinfo_flags -[`end()`]: #net_socket_end_data_encoding +[`socket.end()`]: #net_socket_end_data_encoding [`EventEmitter`]: events.html#events_class_eventemitter [`net.Socket`]: #net_class_net_socket -[`pause()`]: #net_socket_pause -[`resume()`]: #net_socket_resume +[`socket.pause()`]: #net_socket_pause +[`socket.resume()`]: #net_socket_resume [`server.getConnections()`]: #net_server_getconnections_callback [`server.listen(port, host, backlog, callback)`]: #net_server_listen_port_hostname_backlog_callback [`socket.connect(options, connectListener)`]: #net_socket_connect_options_connectlistener [`socket.connect`]: #net_socket_connect_options_connectlistener [`socket.setTimeout()`]: #net_socket_settimeout_timeout_callback [`stream.setEncoding()`]: stream.html#stream_readable_setencoding_encoding -[Readable Stream]: stream.html#stream_class_stream_readable +[Readable]: stream.html#stream_class_stream_readable +[Writable]: stream.html#stream_class_stream_writable From 5ae6a2f6df35425a1710ec23ec27a3e7d8644e8c Mon Sep 17 00:00:00 2001 From: James M Snell Date: Tue, 28 Jun 2016 13:31:24 -0700 Subject: [PATCH 2/3] Fix nit --- doc/api/net.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/net.md b/doc/api/net.md index 66c06b7364f539..44e7487e1e051c 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -190,7 +190,7 @@ The `callback` function is invoked with two arguments: * `err` {Error} `null` if the operation was successful or `Error` if an error occurred. -* `count` {number} The number of connections +* `count` {number} The number of connections. ```js server.getConnections((err, count) => { From af62ea8c36fc7b7298ceeb87e9c7f1a599a45d21 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Mon, 4 Jul 2016 17:28:11 -0700 Subject: [PATCH 3/3] Address nits --- doc/api/net.md | 51 +++++++++++++++++++++++++------------------------- 1 file changed, 26 insertions(+), 25 deletions(-) diff --git a/doc/api/net.md b/doc/api/net.md index 44e7487e1e051c..107e84117a528a 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -56,7 +56,7 @@ added: v0.1.90 --> The `'error'` event is emitted when an error occurs. The [`'close'`][] event -will be emitted immediately following this event. +will be emitted immediately following the `'error'` event. The listener callback is called with the `Error` object passed as the only argument. @@ -72,8 +72,8 @@ server.on('error', (error) => { added: v0.1.90 --> -The `'listening'` event is emitted when the server has been bound after calling -`server.listen`. +The `'listening'` event is emitted when the server has been bound by calling the +`server.listen()` method. The listener callback is called without passing any arguments: @@ -205,7 +205,7 @@ added: v0.5.10 --> * `handle` {Object} -* `backlog` {Number} Defaults to `511` +* `backlog` {Number} Defaults to `511`. * `callback` {Function} The `server.listen()` method instructs the server to begin accepting connections @@ -238,8 +238,8 @@ added: v0.11.14 * `port` {Number} - Optional. * `host` {String} - Optional. * `path` {String} - Optional. - * `backlog` {Number} - Optional. Defaults to `511` - * `exclusive` {Boolean} - Optional. Defaults to `false` + * `backlog` {Number} - Optional. Defaults to `511`. + * `exclusive` {Boolean} - Optional. Defaults to `false`. * `callback` {Function} - Optional. The `server.listen()` method instructs the server to begin accepting connections @@ -314,8 +314,7 @@ net.createServer().listen( ``` The `backlog` argument is the maximum size of the queue of pending connections. -The maximum possible value will be determined by the operating system through -`sysctl` settings such as `tcp_max_syn_backlog` and `somaxconn` on Linux. +The maximum possible value will be determined by the operating system. ### server.listen(port[, hostname][, backlog][, callback]) -The `'close'` event is emitted once the socket is fully closed. +The `'close'` event is emitted once the socket is closed and can no longer be +used to send or receive data. The listener callback is called with a single boolean `had_error` argument. If `true`, then the socket was closed due to a transmission error. @@ -596,11 +596,8 @@ the data is written to the buffer faster than it can be passed to the connection (e.g. when using a slow network connection), the size of the internal buffer can grow. -The value of `socket.bufferSize` represents the number of *characters* pending -in the queue. The number of characters is approximately equal to the number of -bytes, but as the internal queue is managed as `Buffer` instances that may -contain encoded strings, the exact number of bytes is not known until the -`Buffer` data is read. +The value of `socket.bufferSize` represents the amount of data (in bytes) +pending in the queue. In order to avoid large or growing `socket.bufferSize` numbers, attempts should be made to throttle the flow of data written to the socket. @@ -832,6 +829,10 @@ it off. Setting `true` for `noDelay` will immediately fire off data each time Returns a reference to `socket`. +*Note*: Disabling Nagle's algorithm is primarily useful when working with +protocols that use many small payloads as it reduces or eliminates the +buffering that would otherwise occur. + ### socket.setTimeout(timeout[, callback])