Node.js v0.11.9 Manual & Documentation

net#

Stability: 3 - Stable

The net module provides you with an asynchronous network wrapper. It contains methods for creating both servers and clients (called streams). You can include this module with require('net');

net.createServer([options], [connectionListener])#

Creates a new TCP server. The connectionListener argument is automatically set as a listener for the 'connection' event.

options is an object with the following defaults: 

{ allowHalfOpen: false
}

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.

Here is an example of an echo server which listens for connections on port 8124: 

var net = require('net');
var server = net.createServer(function(c) { //'connection' listener
  console.log('server connected');
  c.on('end', function() {
    console.log('server disconnected');
  });
  c.write('hello\r\n');
  c.pipe(c);
});
server.listen(8124, function() { //'listening' listener
  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 

server.listen('/tmp/echo.sock', function() { //'listening' listener

Use nc to connect to a UNIX domain socket server: 

nc -U /tmp/echo.sock

net.connect(options, [connectionListener])#

net.createConnection(options, [connectionListener])#

Constructs a new socket object and opens the socket to the given location. When the socket is established, the 'connect' event will be emitted.

For 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.

  • family : Version of IP stack. Defaults to 4.

For UNIX domain sockets, options argument should be an object which specifies:

  • path: Path the client should connect to (Required).

Common options are:

  • allowHalfOpen: if true, the socket won't automatically send a FIN packet when the other end of the socket sends a FIN packet. Defaults to false. See 'end' event for more information.

The connectListener parameter will be added as an listener for the 'connect' event.

Here is an example of a client of echo server as described previously: 

var net = require('net');
var client = net.connect({port: 8124},
    function() { //'connect' listener
  console.log('client connected');
  client.write('world!\r\n');
});
client.on('data', function(data) {
  console.log(data.toString());
  client.end();
});
client.on('end', function() {
  console.log('client disconnected');
});

To connect on the socket /tmp/echo.sock the second line would just be changed to 

var client = net.connect({path: '/tmp/echo.sock'},

net.connect(port, [host], [connectListener])#

net.createConnection(port, [host], [connectListener])#

Creates a TCP connection to port on host. If host is omitted, 'localhost' will be assumed. The connectListener parameter will be added as an listener for the 'connect' event.

net.connect(path, [connectListener])#

net.createConnection(path, [connectListener])#

Creates unix socket connection to path. The connectListener parameter will be added as an listener for the 'connect' event.

Class: net.Server#

This class is used to create a TCP or UNIX server.

server.listen(port, [host], [backlog], [callback])#

Begin accepting connections on the specified port and host. If the host is omitted, the server will accept connections directed to any IPv4 address (INADDR_ANY). A port value of zero will assign a random port.

Backlog is the maximum length of the queue of pending connections. The actual length will be determined by your 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 an 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. This can be done with 

server.on('error', function (e) {
  if (e.code == 'EADDRINUSE') {
    console.log('Address in use, retrying...');
    setTimeout(function () {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});

(Note: All sockets in Node set SO_REUSEADDR already)

server.listen(path, [callback])#

Start a UNIX socket server listening for connections on the given path.

This function is asynchronous. When the server has been bound,