The net module provides you with an asynchronous network wrapper. It contains\nfunctions for creating both servers and clients (called streams). You can include\nthis module with require('net');.
This class is used to create a TCP or local server.
\nnet.Server is an EventEmitter with the following events:
Emitted when the server closes. Note that if connections exist, this\nevent is not emitted until all connections are ended.
\n", "params": [] }, { "textRaw": "Event: 'connection'", "type": "event", "name": "connection", "meta": { "added": [ "v0.1.90" ] }, "params": [], "desc": "Emitted when a new connection is made. socket is an instance of\nnet.Socket.
Emitted when an error occurs. Unlike net.Socket, the 'close'\nevent will not be emitted directly following this event unless\nserver.close() is manually called. See the example in discussion of\nserver.listen().
Emitted when the server has been bound after calling server.listen.
Returns the bound address, the address family name, and port of the server\nas reported by the operating system if listening on an IP socket.\nUseful to find which port was assigned when getting an OS-assigned address.\nReturns an object with port, family, and address properties:\n{ port: 12346, family: 'IPv4', address: '127.0.0.1' }
For a server listening on a pipe or UNIX domain socket, the name is returned\nas a string.
\nExample:
\nconst server = net.createServer((socket) => {\n socket.end('goodbye\\n');\n}).on('error', (err) => {\n // handle errors here\n throw err;\n});\n\n// grab a random port.\nserver.listen(() => {\n console.log('opened server on', server.address());\n});\nDon't call server.address() until the 'listening' event has been emitted.
Stops the server from accepting new connections and keeps existing\nconnections. This function is asynchronous, the server is finally\nclosed when all connections are ended and the server emits a 'close' event.\nThe optional callback will be called once the 'close' event occurs. Unlike\nthat event, it will be called with an Error as its only argument if the server\nwas not open when it was closed.
Returns server.
Asynchronously get the number of concurrent connections on the server. Works\nwhen sockets were sent to forks.
\nCallback should take two arguments err and count.
The handle object can be set to either a server or socket (anything\nwith an underlying _handle member), or a {fd: <n>} object.
This will cause the server to accept connections on the specified\nhandle, but it is presumed that the file descriptor or handle has\nalready been bound to a port or domain socket.
\nListening on a file descriptor is not supported on Windows.
\nThis function is asynchronous. When the server has been bound,\n'listening' event will be emitted.\nThe last parameter callback will be added as a listener for the\n'listening' event.
The parameter backlog behaves the same as in\nserver.listen([port][, hostname][, backlog][, callback]).
The port, host, and backlog properties of options, as well as the\noptional callback function, behave as they do on a call to\nserver.listen([port][, hostname][, backlog][, callback]).\nAlternatively, the path option can be used to specify a UNIX socket.
If exclusive is false (default), then cluster workers will use the same\nunderlying handle, allowing connection handling duties to be shared. When\nexclusive is true, the handle is not shared, and attempted port sharing\nresults in an error. An example which listens on an exclusive port is\nshown below.
server.listen({\n host: 'localhost',\n port: 80,\n exclusive: true\n});\nNote: The server.listen() method may be called multiple times. Each\nsubsequent call will re-open the server using the provided options.
Start a local socket server listening for connections on the given path.
This function is asynchronous. When the server has been bound,\n'listening' event will be emitted. The last parameter callback\nwill 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\nfilesystem path name. It gets truncated to sizeof(sockaddr_un.sun_path)\nbytes, decreased by 1. It varies on different operating system between 91 and\n107 bytes. The typical values are 107 on Linux and 103 on OS X. The path is\nsubject to the same naming conventions and permissions checks as would be done\non file creation, will be visible in the filesystem, and will persist until\nunlinked.
On Windows, the local domain is implemented using a named pipe. The path must\nrefer to an entry in \\\\?\\pipe\\ or \\\\.\\pipe\\. Any characters are permitted,\nbut the latter may do some processing of pipe names, such as resolving ..\nsequences. Despite appearances, the pipe name space is flat. Pipes will not\npersist, they are removed when the last reference to them is closed. Do not\nforget JavaScript string escaping requires paths to be specified with\ndouble-backslashes, such as:
net.createServer().listen(\n path.join('\\\\\\\\?\\\\pipe', process.cwd(), 'myctl'));\nThe parameter backlog behaves the same as in\nserver.listen([port][, hostname][, backlog][, callback]).
Note: The server.listen() method may be called multiple times. Each\nsubsequent call will re-open the server using the provided options.
Begin accepting connections on the specified port and hostname. If the\nhostname is omitted, the server will accept connections on any IPv6 address\n(::) when IPv6 is available, or any IPv4 address (0.0.0.0) otherwise.\nOmit the port argument, or use a port value of 0, to have the operating system\nassign a random port, which can be retrieved by using server.address().port\nafter the 'listening' event has been emitted.
Backlog is the maximum length of the queue of pending connections.\nThe actual length will be determined by the OS through sysctl settings such as\ntcp_max_syn_backlog and somaxconn on Linux. The default value of this\nparameter is 511 (not 512).
This function is asynchronous. When the server has been bound,\n'listening' event will be emitted. The last parameter callback\nwill be added as a listener for the 'listening' event.
One issue some users run into is getting EADDRINUSE errors. This means that\nanother server is already running on the requested port. One way of handling this\nwould be to wait a second and then try again:
server.on('error', (e) => {\n if (e.code == 'EADDRINUSE') {\n console.log('Address in use, retrying...');\n setTimeout(() => {\n server.close();\n server.listen(PORT, HOST);\n }, 1000);\n }\n});\n(Note: All sockets in Node.js are set SO_REUSEADDR.)
Note: The server.listen() method may be called multiple times. Each\nsubsequent call will re-open the server using the provided options.
Opposite of unref, calling ref on a previously unrefd server will not\nlet the program exit if it's the only server left (the default behavior). If\nthe server is refd calling ref again will have no effect.
Calling unref on a server will allow the program to exit if this is the only\nactive server in the event system. If the server is already unrefd calling\nunref again will have no effect.
The number of concurrent connections on the server.
\nThis becomes null when sending a socket to a child with\nchild_process.fork(). To poll forks and get current number of active\nconnections use asynchronous server.getConnections instead.
A Boolean indicating whether or not the server is listening for\nconnections.
\n" }, { "textRaw": "server.maxConnections", "name": "maxConnections", "meta": { "added": [ "v0.2.0" ] }, "desc": "Set this property to reject connections when the server's connection count gets\nhigh.
\nIt is not recommended to use this option once a socket has been sent to a child\nwith child_process.fork().
This object is an abstraction of a TCP or local socket. net.Socket\ninstances implement a duplex Stream interface. They can be created by the\nuser and used as a client (with connect()) or they can be created by Node.js\nand passed to the user through the 'connection' event of a server.
Construct a new socket object.
\noptions is an object with the following defaults:
{\n fd: null,\n allowHalfOpen: false,\n readable: false,\n writable: false\n}\nfd allows you to specify the existing file descriptor of socket.\nSet readable and/or writable to true to allow reads and/or writes on this\nsocket (NOTE: Works only when fd is passed).\nAbout allowHalfOpen, refer to net.createServer() and 'end' event.
net.Socket instances are EventEmitter with the following events:
Returns the bound address, the address family name and port of the\nsocket as reported by the operating system. Returns an object with\nthree properties, e.g.\n{ port: 12346, family: 'IPv4', address: '127.0.0.1' }
Opens the connection for a given socket.
\nFor TCP sockets, options argument should be an object which specifies:
port: Port the client should connect to (Required).
host: Host the client should connect to. Defaults to 'localhost'.
localAddress: Local interface to bind to for network connections.
localPort: Local port to bind to for network connections.
family : Version of IP stack. Defaults to 4.
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\nspecifies:
path: Path the client should connect to (Required).For either case:
\nNormally this method is not needed, as net.createConnection opens the\nsocket. Use this only if you are implementing a custom Socket.
This function is asynchronous. When the 'connect' event is emitted the\nsocket is established. If there is a problem connecting, the 'connect' event\nwill not be emitted, the 'error' event will be emitted with the exception.
The connectListener parameter will be added as a listener for the\n'connect' event.
As socket.connect(options[, connectListener]),\nwith options as either {port: port, host: host} or {path: path}.
As socket.connect(options[, connectListener]),\nwith options as either {port: port, host: host} or {path: path}.
Ensures that no more I/O activity happens on this socket. Only necessary in\ncase of errors (parse error or so).
\nIf exception is specified, an 'error' event will be emitted and any\nlisteners for that event will receive exception as an argument.
Half-closes the socket. i.e., it sends a FIN packet. It is possible the\nserver will still send some data.
\nIf data is specified, it is equivalent to calling\nsocket.write(data, encoding) followed by socket.end().
Pauses the reading of data. That is, 'data' events will not be emitted.\nUseful to throttle back an upload.
Opposite of unref, calling ref on a previously unrefd socket will not\nlet the program exit if it's the only socket left (the default behavior). If\nthe socket is refd calling ref again will have no effect.
Resumes reading after a call to pause().
Set the encoding for the socket as a Readable Stream. See\nstream.setEncoding() for more information.
Enable/disable keep-alive functionality, and optionally set the initial\ndelay before the first keepalive probe is sent on an idle socket.\nenable defaults to false.
Set initialDelay (in milliseconds) to set the delay between the last\ndata packet received and the first keepalive probe. Setting 0 for\ninitialDelay will leave the value unchanged from the default\n(or previous) setting. Defaults to 0.
Disables the Nagle algorithm. By default TCP connections use the Nagle\nalgorithm, they buffer data before sending it off. Setting true for\nnoDelay will immediately fire off data each time socket.write() is called.\nnoDelay defaults to true.
Sets the socket to timeout after timeout milliseconds of inactivity on\nthe socket. By default net.Socket do not have a timeout.
When an idle timeout is triggered the socket will receive a 'timeout'\nevent but the connection will not be severed. The user must manually end()\nor destroy() the socket.
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\n'timeout' event.
Calling unref on a socket will allow the program to exit if this is the only\nactive socket in the event system. If the socket is already unrefd calling\nunref again will have no effect.
Sends data on the socket. The second parameter specifies the encoding in the\ncase of a string--it defaults to UTF8 encoding.
\nReturns true if the entire data was flushed successfully to the kernel\nbuffer. Returns false if all or part of the data was queued in user memory.\n'drain' will be emitted when the buffer is again free.
The optional callback parameter will be executed when the data is finally\nwritten out - this may not be immediately.
Emitted once the socket is fully closed. The argument had_error is a boolean\nwhich says if the socket was closed due to a transmission error.
Emitted when a socket connection is successfully established.\nSee connect().
Emitted when data is received. The argument data will be a Buffer or\nString. Encoding of data is set by socket.setEncoding().\n(See the Readable Stream section for more information.)
Note that the data will be lost if there is no listener when a Socket\nemits a 'data' event.
Emitted when the write buffer becomes empty. Can be used to throttle uploads.
\nSee also: the return values of socket.write()
Emitted when the other end of the socket sends a FIN packet.
\nBy default (allowHalfOpen == false) the socket will destroy its file\ndescriptor once it has written out its pending write queue. However, by\nsetting allowHalfOpen == true the socket will not automatically end()\nits side allowing the user to write arbitrary amounts of data, with the\ncaveat that the user is required to end() their side now.
Emitted when an error occurs. The 'close' event will be called directly\nfollowing this event.
Emitted after resolving the hostname but before connecting.\nNot applicable to UNIX sockets.
\nerr {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.Emitted if the socket times out from inactivity. This is only to notify that\nthe socket has been idle. The user must manually close the connection.
\nSee also: socket.setTimeout()
net.Socket has the property that socket.write() always works. This is to\nhelp users get up and running quickly. The computer cannot always keep up\nwith the amount of data that is written to a socket - the network connection\nsimply might be too slow. Node.js will internally queue up the data written to a\nsocket and send it out over the wire when it is possible. (Internally it is\npolling on the socket's file descriptor for being writable).
The consequence of this internal buffering is that memory may grow. This\nproperty shows the number of characters currently buffered to be written.\n(Number of characters is approximately equal to the number of bytes to be\nwritten, but the buffer may contain strings, and the strings are lazily\nencoded, so the exact number of bytes is not known.)
\nUsers who experience large or growing bufferSize should attempt to\n"throttle" the data flows in their program with pause() and resume().
The amount of received bytes.
\n" }, { "textRaw": "socket.bytesWritten", "name": "bytesWritten", "meta": { "added": [ "v0.5.3" ] }, "desc": "The amount of bytes sent.
\n" }, { "textRaw": "socket.connecting", "name": "connecting", "meta": { "added": [ "v6.1.0" ] }, "desc": "If true - socket.connect(options[, connectListener]) was called and\nhaven't yet finished. Will be set to false before emitting connect event\nand/or calling socket.connect(options[, connectListener])'s callback.
A Boolean value that indicates if the connection is destroyed or not. Once a\nconnection is destroyed no further data can be transferred using it.
\n" }, { "textRaw": "socket.localAddress", "name": "localAddress", "meta": { "added": [ "v0.9.6" ] }, "desc": "The string representation of the local IP address the remote client is\nconnecting on. For example, if you are listening on '0.0.0.0' and the\nclient connects on '192.168.1.1', the value would be '192.168.1.1'.
The numeric representation of the local port. For example,\n80 or 21.
The string representation of the remote IP address. For example,\n'74.125.127.100' or '2001:4860:a005::68'. Value may be undefined if\nthe socket is destroyed (for example, if the client disconnected).
The string representation of the remote IP family. 'IPv4' or 'IPv6'.
The numeric representation of the remote port. For example,\n80 or 21.
A factory function, which returns a new net.Socket and automatically\nconnects with the supplied options.
The options are passed to both the net.Socket constructor and the\nsocket.connect method.
The connectListener parameter will be added as a listener for the\n'connect' event once.
Here is an example of a client of the previously described echo server:
\nconst net = require('net');\nconst client = net.connect({port: 8124}, () => {\n // 'connect' listener\n console.log('connected to server!');\n client.write('world!\\r\\n');\n});\nclient.on('data', (data) => {\n console.log(data.toString());\n client.end();\n});\nclient.on('end', () => {\n console.log('disconnected from server');\n});\nTo connect on the socket /tmp/echo.sock the second line would just be\nchanged to
const client = net.connect({path: '/tmp/echo.sock'});\nA factory function, which returns a new unix net.Socket and automatically\nconnects to the supplied path.
The connectListener parameter will be added as a listener for the\n'connect' event once.
A factory function, which returns a new net.Socket and automatically\nconnects to the supplied port and host.
If host is omitted, 'localhost' will be assumed.
The connectListener parameter will be added as a listener for the\n'connect' event once.
A factory function, which returns a new net.Socket and automatically\nconnects with the supplied options.
The options are passed to both the net.Socket constructor and the\nsocket.connect method.
Passing timeout as an option will call socket.setTimeout() after the socket is created, but before it is connecting.
The connectListener parameter will be added as a listener for the\n'connect' event once.
Following is an example of a client of the echo server described\nin the net.createServer() section:
const net = require('net');\nconst client = net.createConnection({port: 8124}, () => {\n //'connect' listener\n console.log('connected to server!');\n client.write('world!\\r\\n');\n});\nclient.on('data', (data) => {\n console.log(data.toString());\n client.end();\n});\nclient.on('end', () => {\n console.log('disconnected from server');\n});\nTo connect on the socket /tmp/echo.sock the second line would just be\nchanged to
const client = net.connect({path: '/tmp/echo.sock'});\nA factory function, which returns a new unix net.Socket and automatically\nconnects to the supplied path.
The connectListener parameter will be added as a listener for the\n'connect' event once.
A factory function, which returns a new net.Socket and automatically\nconnects to the supplied port and host.
If host is omitted, 'localhost' will be assumed.
The connectListener parameter will be added as a listener for the\n'connect' event once.
Creates a new server. The connectionListener argument is\nautomatically set as a listener for the 'connection' event.
options is an object with the following defaults:
{\n allowHalfOpen: false,\n pauseOnConnect: false\n}\nIf allowHalfOpen is true, then the socket won't automatically send a FIN\npacket when the other end of the socket sends a FIN packet. The socket becomes\nnon-readable, but still writable. You should call the end() method explicitly.\nSee 'end' event for more information.
If pauseOnConnect is true, then the socket associated with each incoming\nconnection will be paused, and no data will be read from its handle. This allows\nconnections to be passed between processes without any data being read by the\noriginal process. To begin reading data from a paused socket, call resume().
Here is an example of an echo server which listens for connections\non port 8124:
\nconst net = require('net');\nconst server = net.createServer((c) => {\n // 'connection' listener\n console.log('client connected');\n c.on('end', () => {\n console.log('client disconnected');\n });\n c.write('hello\\r\\n');\n c.pipe(c);\n});\nserver.on('error', (err) => {\n throw err;\n});\nserver.listen(8124, () => {\n console.log('server bound');\n});\nTest this by using telnet:
$ telnet localhost 8124\nTo listen on the socket /tmp/echo.sock the third line from the last would\njust be changed to
server.listen('/tmp/echo.sock', () => {\n console.log('server bound');\n});\nUse nc to connect to a UNIX domain socket server:
$ nc -U /tmp/echo.sock\nTests if input is an IP address. Returns 0 for invalid strings,\nreturns 4 for IP version 4 addresses, and returns 6 for IP version 6 addresses.
\n", "signatures": [ { "params": [ { "name": "input" } ] } ] }, { "textRaw": "net.isIPv4(input)", "type": "method", "name": "isIPv4", "meta": { "added": [ "v0.3.0" ] }, "desc": "Returns true if input is a version 4 IP address, otherwise returns false.
\n", "signatures": [ { "params": [ { "name": "input" } ] } ] }, { "textRaw": "net.isIPv6(input)", "type": "method", "name": "isIPv6", "meta": { "added": [ "v0.3.0" ] }, "desc": "Returns true if input is a version 6 IP address, otherwise returns false.
\n", "signatures": [ { "params": [ { "name": "input" } ] } ] } ], "type": "module", "displayName": "Net" } ] }