diff --git a/doc/api/net.md b/doc/api/net.md index 3465ece47be9c0..0c14e663eeb7b9 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -2,9 +2,14 @@ > 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 asynchronous network API for creating stream-based +servers ([`net.createServer()`][]) and clients ([`net.createConnection()`][]) +that implement TCP or local communications (domain sockets on UNIX, named pipes +on Windows). It can be accessed using: + +```js +const net = require('net'); +``` ## Class: net.Server -Emitted when the server has been bound after calling `server.listen`. +Emitted when the server has been bound after calling [`server.listen()`][]. ### server.address() * `handle` {Object} -* `backlog` {number} -* `callback` {Function} +* `backlog` {number} Common parameter of [`server.listen()`][] functions +* `callback` {Function} Common parameter of [`server.listen()`][] functions -The `handle` object can be set to either a server or socket (anything -with an underlying `_handle` member), or a `{fd: }` object. +Start a server listening for connections on a given `handle` that has +already been bound to a port, a UNIX domain socket, or a Windows named pipe. -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. +The `handle` object can be either a server, a socket (anything with an +underlying `_handle` member), or an object with a `fd` member that is a +valid file descriptor. -Listening on a file descriptor is not supported on Windows. +*Note*: Listening on a file descriptor is not supported on Windows. -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 parameter `backlog` behaves the same as in -[`server.listen([port][, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`]. - -### server.listen(options[, callback]) +#### server.listen(options[, callback]) -* `options` {Object} - Required. Supports the following properties: - * `port` {number} - Optional. - * `host` {string} - Optional. - * `backlog` {number} - Optional. - * `path` {string} - Optional. - * `exclusive` {boolean} - Optional. -* `callback` {Function} - Optional. +* `options` {Object} Required. Supports the following properties: + * `port` {number} Optional. + * `host` {string} Optional. + * `path` {string} Optional. Will be ignored if `port` is specified. + * `backlog` {number} Optional. Common parameter of [`server.listen()`][] + functions + * `exclusive` {boolean} Optional. Default to `false` +* `callback` {Function} Optional. Common parameter of [`server.listen()`][] + functions -The `port`, `host`, and `backlog` properties of `options`, as well as the -optional callback function, behave as they do on a call to -[`server.listen([port][, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`]. -Alternatively, the `path` option can be used to specify a UNIX socket. +If `port` is specified, it behaves the same as +[`server.listen([port][, hostname][, backlog][, callback])`][`server.listen(port, host)`]. +Otherwise, if `path` is specified, it behaves the same as +[`server.listen(path[, backlog][, callback])`][`server.listen(path)`]. +If none of them is specified, an error will be thrown. If `exclusive` is `false` (default), then cluster workers will use the same underlying handle, allowing connection handling duties to be shared. When @@ -175,24 +230,17 @@ server.listen({ }); ``` -*Note*: The `server.listen()` method may be called multiple times. Each -subsequent call will *re-open* the server using the provided options. - -### server.listen(path[, backlog][, callback]) +#### server.listen(path[, backlog][, callback]) -* `path` {string} -* `backlog` {number} -* `callback` {Function} +* `path` {String} +* `backlog` {number} Common parameter of [`server.listen()`][] functions +* `callback` {Function} Common parameter of [`server.listen()`][] functions Start a local socket server listening for connections on the given `path`. -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. - On UNIX, the local domain is usually known as the UNIX domain. The path is a filesystem path name. It gets truncated to `sizeof(sockaddr_un.sun_path)` bytes, decreased by 1. It varies on different operating system between 91 and @@ -214,19 +262,22 @@ net.createServer().listen( path.join('\\\\?\\pipe', process.cwd(), 'myctl')) ``` -The parameter `backlog` behaves the same as in -[`server.listen([port][, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`]. - -*Note*: The `server.listen()` method may be called multiple times. Each -subsequent call will *re-open* the server using the provided options. - -### server.listen([port][, hostname][, backlog][, callback]) +#### server.listen([port][, host][, backlog][, callback]) +* `port` {number} +* `host` {string} +* `backlog` {number} Common parameter of [`server.listen()`][] functions +* `callback` {Function} Common parameter of [`server.listen()`][] functions + +Start a TCP server listening for connections on the given `port` and `host`. -Begin accepting connections on the specified `port` and `hostname`. If the -`hostname` is omitted, the server will accept connections on the +If `port` is omitted or is 0, the operating system will assign an arbitrary +unused port, which can be retrieved by using `server.address().port` +after the [`'listening'`][] event has been emitted. + +If `host` is omitted, the server will accept connections on the [unspecified IPv6 address][] (`::`) when IPv6 is available, or the [unspecified IPv4 address][] (`0.0.0.0`) otherwise. @@ -234,40 +285,6 @@ Begin accepting connections on the specified `port` and `hostname`. If the [unspecified IPv6 address][] (`::`) may cause the `net.Server` to also listen on the [unspecified IPv4 address][] (`0.0.0.0`). -Omit the port argument, or use a port value of `0`, to have the operating system -assign a random port, which can be retrieved by using `server.address().port` -after the `'listening'` event has been emitted. - -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). - -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. - -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: - -```js -server.on('error', (e) => { - if (e.code == 'EADDRINUSE') { - console.log('Address in use, retrying...'); - setTimeout(() => { - server.close(); - server.listen(PORT, HOST); - }, 1000); - } -}); -``` - -(Note: All sockets in Node.js are set `SO_REUSEADDR`.) - -*Note*: The `server.listen()` method may be called multiple times. Each -subsequent call will *re-open* the server using the provided options. - ### server.listening -Emitted when the other end of the socket sends a FIN packet. +Emitted when the other end of the socket sends a FIN packet, thus ending the +readable side of the socket. -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. +By default (`allowHalfOpen` is `false`) the socket will send a FIN packet +back and destroy its file descriptor once it has written out its pending +write queue. However, if `allowHalfOpen` is set to `true`, the socket will +not automatically [`end()`][`socket.end()`] its writable side, allowing the +user to write arbitrary amounts of data. The user must call +[`end()`][`socket.end()`] explicitly to close the connection (i.e. sending a +FIN packet back). ### Event: 'error' -Creates a new server. The `connectionListener` argument is -automatically set as a listener for the [`'connection'`][] event. +Creates a new TCP or local server. -`options` is an object with the following defaults: +* `options` {Object} + * `allowHalfOpen` {boolean} Default to `false`. Indicates whether half-opened + TCP connections are allowed. + * `pauseOnConnect` {boolean} Default to `false`. Indicates whether the socket + should be paused on incoming connections. +* `connectionListener` {Function} Automatically set as a listener for the + [`'connection'`][] event -```js -{ - allowHalfOpen: false, - pauseOnConnect: false -} -``` +If `allowHalfOpen` is set to `true`, when the other end of the socket +sends a FIN packet, the server will only send a FIN packet back when +[`socket.end()`][] is explicitly called, until then the connection is +half-closed (non-readable but still writable). See [`'end'`][] event +and [RFC 1122][half-closed] for more information. -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. +If `pauseOnConnect` is set to `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 +[`socket.resume()`][]. -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 server can be a TCP server or a local server, depending on what it +[`listen()`][`server.listen()`] to. -Here is an example of an echo server which listens for connections +Here is an example of an TCP echo server which listens for connections on port 8124: ```js @@ -947,22 +979,30 @@ Returns true if input is a version 6 IP address, otherwise returns false. [`'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_exception [`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 [`EventEmitter`]: events.html#events_class_eventemitter +[`net.createConnection()`]: #net_net_createconnection_options_connectlistener [`net.createServer()`]: #net_net_createserver_options_connectionlistener +[`net.Server`]: #net_class_net_server [`net.Socket`]: #net_class_net_socket -[`pause()`]: #net_socket_pause -[`resume()`]: #net_socket_resume [`server.getConnections()`]: #net_server_getconnections_callback -[`server.listen(port, host, backlog, callback)`]: #net_server_listen_port_hostname_backlog_callback +[`server.listen()`]: #net_server_listen +[`server.listen(handle)`]: #net_server_listen_handle_backlog_callback +[`server.listen(options)`]: #net_server_listen_options_callback +[`server.listen(path)`]: #net_server_listen_path_backlog_callback +[`server.listen(port, host)`]: #net_server_listen_port_host_backlog_callback [`server.close()`]: #net_server_close_callback [`socket.connect(options, connectListener)`]: #net_socket_connect_options_connectlistener [`socket.connect`]: #net_socket_connect_options_connectlistener +[`socket.destroy()`]: #net_socket_destroy_exception +[`socket.end()`]: #net_socket_end_data_encoding [`socket.setTimeout()`]: #net_socket_settimeout_timeout_callback +[`socket.resume()`]: #net_socket_resume +[`socket.pause()`]: #net_socket_pause [`stream.setEncoding()`]: stream.html#stream_readable_setencoding_encoding +[half-closed]: https://tools.ietf.org/html/rfc1122#section-4.2.2.13 [Readable Stream]: stream.html#stream_class_stream_readable +[socket(7)]: http://man7.org/linux/man-pages/man7/socket.7.html [unspecified IPv6 address]: https://en.wikipedia.org/wiki/IPv6_address#Unspecified_address [unspecified IPv4 address]: https://en.wikipedia.org/wiki/0.0.0.0