Сетевой модуль

Модуль net предоставляет асинхронную обёртку для сетевого взаимодействия. Он содержит функции для создания серверов и клиентов (называемых потоками). Этот модуль можно включить с помощью require('net');.

Класс: net.Server

Этот класс используется для создания TCP или локального сервера.

net.Server является EventEmitter с следующими событиями:

Событие: 'close'

Вызывается при закрытии сервера. Обратите внимание, что если соединения существуют, это событие не вызывается до тех пор, пока все соединения не будут закрыты.

Событие: 'connection'

• <net.Socket> Объект подключения

Вызывается при установлении нового соединения. socket является экземпляром net.Socket.

Событие: 'error'

• <Error>

Вызывается при возникновении ошибки. В отличие от net.Socket, событие 'close' не будет вызвано непосредственно после этого события, если явно не вызвана функция server.close(). См. пример в описании server.listen().

Событие: 'listening'

Вызывается после привязки сервера, вызванной функцией server.listen.

server.address()

Возвращает привязанный адрес, имя семейства адресов и порт сервера, как сообщается операционной системой, если сервер прослушивает IP-сокет. Полезно для определения назначенного порта при получении адреса, назначенного операционной системой. Возвращает объект со свойствами port, family, и address: { port: 12346, family: 'IPv4', address: '127.0.0.1' }

Для сервера, прослушивающего насок или UNIX-сокет, имя возвращается как строка.

Пример:

const server = net.createServer((socket) => {
  socket.end('goodbye\n');
}).on('error', (err) => {
  // handle errors here
  throw err;
});

// grab a random port.
server.listen(() => {
  console.log('opened server on', server.address());
});

Не вызывайте server.address() до тех пор, пока не будет вызвано событие 'listening'.

server.close([callback])

• Возвращает: <net.Server>

Останавливает сервер от принятия новых соединений и сохраняет существующие соединения. Эта функция асинхронная; сервер окончательно закрывается, когда все соединения завершены, и сервер вызывает событие 'close'. Необязательный callback будет вызван, как только произойдёт событие 'close'. В отличие от события, он будет вызван с ошибкой в качестве единственного аргумента, если сервер был закрыт, когда он ещё не был открыт.

Возвращает server.

server.connections

Количество одновременных подключений на сервере.

Это становится null при отправке сокета дочернему процессу с помощью child_process.fork(). Для опроса вилок и получения текущего числа активных подключений используйте асинхронную функцию server.getConnections.

server.getConnections(callback)

• Возвращает: <net.Server>

Асинхронно получает количество одновременных подключений на сервере. Работает, когда сокеты были отправлены вилкам.

Обработчик должен принять два аргумента err и count.

server.listen(handle[, backlog][, callback])

• handle <Объект>
• backlog <число>
• callback <Функция>
• Возвращает: <net.Server>

Объект handle может быть настроен на сервер или сокет (любой объект с внутренним членом _handle), или объект {fd: <n>}.

Это заставит сервер принимать соединения на указанном handle, но предполагается, что дескриптор файла или handle уже привязан к порту или доменному сокету.

Прослушивание на дескрипторе файла не поддерживается в Windows.

Эта функция асинхронная. Когда сервер будет привязан, будет вызвано событие 'listening'. Последний параметр callback будет добавлен в качестве обработчика события 'listening'.

Параметр backlog действует так же, как и в server.listen([port][, hostname][, backlog][, callback]).

server.listen(options[, callback])

• options <Объект> - Обязательный. Поддерживает следующие свойства:
  • port <число> - Необязательный.
  • host <строка> - Необязательный.
  • backlog <число> - Необязательный.
  • path <строка> - Необязательный.
  • exclusive <логическое> - Необязательный.
• callback <Функция> - Необязательный.
• Возвращает: <net.Server>

Свойства port, host, и backlog объекта options, а также необязательная функция обратного вызова, ведут себя так же, как и при вызове server.listen([port][, hostname][, backlog][, callback]). В качестве альтернативы, можно использовать опцию path для указания UNIX-сокету.

Если exclusive установлено в false (по умолчанию), тогда рабочие процессы кластера будут использовать тот же underlying handle, что позволит совместно использовать задачи обработки соединений. Когда exclusive установлено в true, handle не совместно используется, а попытка совместного использования порта приводит к ошибке. Пример прослушивания на эксклюзивном порте показан ниже.

server.listen({
  host: 'localhost',
  port: 80,
  exclusive: true
});

Примечание: Метод server.listen() может быть вызван несколько раз. Каждый последующий вызов переоткрывает сервер с использованием предоставленных параметров.

server.listen(path[, backlog][, callback])

• path <строка>
• backlog <число>
• callback <Функция>
• Возвращает: <net.Server>

Запустить локальный сокет-сервер, прослушивающий соединения на указанном path.

Эта функция асинхронная. Когда сервер будет привязан, будет вызвано событие 'listening'. Последний параметр callback будет добавлен в качестве обработчика события 'listening'.

В UNIX локальный домен обычно называется UNIX-доменом. Путь — это имя пути в файловой системе. Он усекается до sizeof(sockaddr_un.sun_path) байт, уменьшенное на 1. Это значение варьируется в зависимости от операционной системы от 91 до 107 байт. Типичные значения составляют 107 на Linux и 103 на OS X. Путь подчиняется тем же соглашениям об именовании и проверкам разрешений, что и при создании файла, будет виден в файловой системе и останется до удаления.

В Windows локальный домен реализуется с помощью именованной трубы. Путь должен указывать на запись в \\?\pipe\ или \\.\pipe\ . Разрешены любые символы, но последний может выполнять некоторые операции с именами труб, такие как разрешение .. последовательностей. Несмотря на внешнее представление, пространство имён труб плоское. Трубы не сохраняются, они удаляются, когда закрывается последняя ссылка на них. Не забывайте, что эскейпинг строк JavaScript требует указания путей с двойными обратными слешами, например:

net.createServer().listen(
  path.join('\\\\?\\pipe', process.cwd(), 'myctl'));

Параметр backlog работает так же, как и в server.listen([port][, hostname][, backlog][, callback]).

Примечание: Метод server.listen() может быть вызван несколько раз. Каждый последующий вызов переоткрывает сервер с использованием предоставленных параметров.

server.listen([port][, hostname][, backlog][, callback])

• Возвращает: <net.Server>

Начать прием подключений на указанном port и hostname. Если hostname опущено, сервер будет принимать подключения на любой IPv6-адрес (::) при доступности IPv6 или на любой IPv4-адрес (0.0.0.0) в противном случае. Опустите аргумент порта или используйте значение порта 0, чтобы операционная система назначила случайный порт, который можно получить, используя server.address().port после того, как событие 'listening' будет испущено.

Backlog — максимальная длина очереди ожидающих подключений. Фактическая длина будет определена ОС с помощью настроек sysctl, таких как tcp_max_syn_backlog и somaxconn в Linux. Значение по умолчанию этого параметра равно 511 (а не 512).

Эта функция асинхронна. Когда сервер связан, будет испущено событие 'listening'. Последний параметр callback будет добавлен как обработчик события 'listening'.

Одна из проблем, с которой сталкиваются некоторые пользователи, — это получение ошибок EADDRINUSE. Это означает, что другой сервер уже запущен на запрошенном порту. Один из способов обработки этого — подождать секунду, а затем повторить попытку:

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

(Примечание: все сокеты в Node.js установлены SO_REUSEADDR.)

Примечание: метод server.listen() может вызываться несколько раз. Каждый последующий вызов будет переоткрывать сервер с использованием предоставленных параметров.

server.listening

Булево значение, указывающее, прослушивает ли сервер подключения.

server.maxConnections

Установите это свойство, чтобы отклонять подключения, когда количество подключений сервера становится высоким.

Не рекомендуется использовать этот параметр после отправки сокета в дочерний процесс с помощью child_process.fork().

server.ref()

• Возвращает: <net.Server>

Противоположное unref, вызов ref на ранее unref сервере не позволит программе завершиться, если это единственный оставшийся сервер (поведение по умолчанию). Если сервер refd, повторный вызов ref не повлияет.

server.unref()

• Возвращает: <net.Server>

Вызов unref на сервере позволит программе завершиться, если это единственный активный сервер в системе событий. Если сервер уже unrefd, повторный вызов unref не повлияет.

Класс: net.Socket

Этот объект является абстракцией TCP- или локального сокета. Экземпляры net.Socket реализуют интерфейс дуплексного потока Stream. Их можно создавать пользователю и использовать в качестве клиента (с помощью connect()) или их можно создавать Node.js и передавать пользователю через событие 'connection' сервера.

new net.Socket([options])

Создает новый объект сокета.

options — объект со следующими значениями по умолчанию:

{
  fd: null,
  allowHalfOpen: false,
  readable: false,
  writable: false
}

fd позволяет указать существующий дескриптор файла сокета. Установите readable и/или writable в true для разрешения чтения и/или записи в этом сокете (ПРИМЕЧАНИЕ: работает только при передаче fd). О allowHalfOpen, см. net.createServer() и событие 'end'.

Экземпляры net.Socket являются EventEmitter со следующими событиями:

Событие: 'close'

• had_error <boolean> true если у сокета была ошибка передачи.

Выдается, когда сокет полностью закрыт. Аргумент had_error — булево значение, указывающее, был ли сокет закрыт из-за ошибки передачи.

Событие: 'connect'

Выдается, когда соединение сокета успешно установлено. См. connect().

Событие: 'data'

• <Buffer>

Выдается при получении данных. Аргумент data будет <Buffer> или String. Кодировка данных задается socket.setEncoding(). (См. раздел Потоковый поток Readable для получения дополнительной информации.)

Обратите внимание, что данные будут потеряны, если нет обработчика, когда Socket испускает событие 'data'.

Событие: 'drain'

Выдается, когда буфер записи становится пустым. Может использоваться для ограничения загрузок.

См. также: возвращаемые значения socket.write()

Событие: 'end'

Выдается, когда другой конец сокета отправляет пакет FIN.

По умолчанию (allowHalfOpen == false) сокет уничтожит свой дескриптор файла после записи в очередь ожидающих записей. Однако, установив allowHalfOpen == true, сокет не будет автоматически end() своей стороны, что позволит пользователю записывать произвольное количество данных, с оговоркой, что пользователь теперь обязан end() свою сторону.

Событие: 'error'

• <Error>

Выдается при возникновении ошибки. Событие 'close' будет вызвано непосредственно после этого события.

Событие: 'lookup'

Выдается после разрешения имени хоста, но перед подключением. Не применимо к UNIX-сокет.

• err <Error> | <null> Объект ошибки. См. dns.lookup().
• address <string> IP-адрес.
• family <string> | <null> Тип адреса. См. dns.lookup().
• host <string> Имя хоста.

Событие: 'timeout'

Выдается, если сокет истекает по причине бездействия. Это только для уведомления о том, что сокет простаивает. Пользователь должен вручную закрыть соединение.

См. также: socket.setTimeout()

socket.address()

Возвращает связанный адрес, имя семейства адресов и порт сокета, как сообщается операционной системой. Возвращает объект с тремя свойствами, например { port: 12346, family: 'IPv4', address: '127.0.0.1' }

socket.bufferSize

net.Socket имеет свойство, что socket.write() всегда работает. Это помогает пользователям быстро начать работу. Компьютер не всегда может уследить за объемом данных, записываемым в сокет — соединение с сетью может просто быть слишком медленным. Node.js будет внутренне очередировать данные, записываемые в сокет, и отправлять их по проводам, когда это возможно. (Внутренне происходит опрос дескриптора файла сокета на доступность для записи).

Последствием этого внутреннего буферирования является то, что объем памяти может увеличиваться. Это свойство показывает количество символов, в настоящее время буферизованных для записи. (Количество символов приблизительно равно количеству байтов для записи, но буфер может содержать строки, а строки кодируются лениво, поэтому точное количество байтов неизвестно.)

Пользователи, которые сталкиваются с большими или растущими bufferSize должны попытаться «ограничить» потоки данных в своей программе с помощью pause() и resume().

socket.bytesRead

Количество полученных байтов.

socket.bytesWritten

Количество отправленных байтов.

socket.connect(options[, connectListener])

Открывает соединение для заданного сокета.

Для TCP-сокетов аргумент options должен быть объектом, который определяет:

• port: Порт, к которому должен подключиться клиент (Обязательно).

• host: Хост, к которому должен подключиться клиент. По умолчанию 'localhost'.

• localAddress: Локальный интерфейс для привязки к сетевым подключениям.

• localPort: Локальный порт для привязки к сетевым подключениям.

• family : Версия стека IP. По умолчанию 4.

• hints: dns.lookup() подсказки. По умолчанию 0.

• lookup : Пользовательская функция поиска. По умолчанию dns.lookup.

Для сокетов локального домена, аргумент options должен быть объектом, который определяет:

• path: Путь, к которому должен подключиться клиент (обязательно).

В любом случае:

• Возвращает: <net.Socket> Сам сокет.

Обычно этот метод не нужен, так как net.createConnection открывает сокет. Используйте его только в случае реализации пользовательского сокета.

Эта функция асинхронна. При вызове события 'connect' сокет устанавливается. Если возникла проблема с подключением, событие 'connect' не будет вызвано, а событие 'error' будет вызвано с исключением.

Параметр connectListener будет добавлен в качестве слушателя события 'connect'.

socket.connect(path[, connectListener])

socket.connect(port[, host][, connectListener])

Как socket.connect(options[, connectListener]), с опциями в виде {port: port, host: host} или {path: path}.

• Возвращает: <net.Socket> Сам сокет.

socket.connecting

Если true - socket.connect(options[, connectListener]) был вызван и еще не завершен. Будет установлено в false перед вызовом события connect и/или вызовом обратного вызова socket.connect(options[, connectListener]).

socket.destroy([exception])

Гарантирует, что больше нет операций ввода-вывода на этом сокете. Необходимо только в случае ошибок (ошибок разбора и т. п.).

Если exception указан, событие 'error' будет выведено, и все слушатели этого события получат exception в качестве аргумента.

socket.destroyed

Булевое значение, указывающее, разрушен ли соединение или нет. После разрушения соединения дальнейшая передача данных через него невозможна.

socket.end([data][, encoding])

• Возвращает: <net.Socket> Сам сокет.

Полузакрывает сокет. Т.е., отправляет пакет FIN. Возможно, сервер все еще будет отправлять данные.

Если data указан, это эквивалентно вызову socket.write(data, encoding) и затем socket.end().

Возвращает socket.

socket.localAddress

Строковое представление локального IP-адреса, на котором подключается удаленный клиент. Например, если вы слушаете на '0.0.0.0' и клиент подключается по '192.168.1.1', значение будет '192.168.1.1'.

socket.localPort

Числовое представление локального порта. Например, 80 или 21.

socket.pause()

Приостанавливает чтение данных. То есть, события 'data' не будут выводиться. Полезно для ограничения загрузки.

socket.ref()

• Возвращает: <net.Socket> Сам сокет.

Противоположность unref, вызов ref на ранее unref сокете не позволит программе завершиться, если это единственный оставшийся сокет (по умолчанию). Если сокет refd, повторный вызов ref не повлияет.

socket.remoteAddress

Строковое представление удаленного IP-адреса. Например, '74.125.127.100' или '2001:4860:a005::68'. Значение может быть undefined если сокет разрушен (например, если клиент отключился).

socket.remoteFamily

Строковое представление семейства удаленного IP-адреса. 'IPv4' или 'IPv6'.

socket.remotePort

Числовое представление удаленного порта. Например, 80 или 21.

socket.resume()

Возобновляет чтение после вызова pause().

socket.setEncoding([encoding])

• Возвращает: <net.Socket> Сам сокет.

Устанавливает кодировку для сокета как Поток чтения. См. stream.setEncoding() для получения дополнительной информации.

socket.setKeepAlive([enable][, initialDelay])

• Возвращает: <net.Socket> Сам сокет.

Включение/выключение функции keep-alive и, необязательно, установка начальной задержки перед отправкой первого запроса keep-alive для сокета в режиме простоя. enable по умолчанию false.

Установите initialDelay (в миллисекундах), чтобы установить задержку между последним полученным пакетом данных и первым запросом keep-alive. Установка 0 для initialDelay оставит значение неизменным от значения по умолчанию (или предыдущего) параметра. По умолчанию 0.

socket.setNoDelay([noDelay])

• Возвращает: <net.Socket> Сам сокет.

Отключает алгоритм Найгла. По умолчанию TCP-соединения используют алгоритм Найгла, они буферизируют данные перед отправкой. Установка true для noDelay немедленно отправит данные каждый раз при вызове socket.write() . noDelay по умолчанию true.

socket.setTimeout(timeout[, callback])

• Возвращает: <net.Socket> Сам сокет.

Устанавливает таймаут сокета через timeout миллисекунд бездействия на сокете. По умолчанию у net.Socket нет таймаута.

При срабатывании таймаута бездействия сокет получит событие 'timeout', но соединение не будет разорвано. Пользователь должен вручную end() или destroy() сокет.

Если timeout равно 0, то существующий таймаут бездействия отключен.

Необязательный параметр callback будет добавлен в качестве одноразового слушателя для события 'timeout'.

socket.unref()

• Возвращает: <net.Socket> Сам сокет.

Вызов unref на сокете позволит программе завершиться, если это единственный активный сокет в системе событий. Если сокет уже unrefd, повторный вызов unref не повлияет.

socket.write(data[, encoding][, callback])

Отправляет данные по сокету. Второй параметр указывает кодировку в случае строки — по умолчанию UTF8.

Возвращает true если все данные успешно сброшены в буфер ядра. Возвращает false если все или часть данных были помещены в память пользователя. 'drain' будет выведено, когда буфер снова будет свободен.

Необязательный параметр callback будет выполнен, когда данные будут окончательно отправлены — это может не произойти сразу.

net.connect(options[, connectListener])

Функция-фабрика, которая возвращает новый net.Socket и автоматически подключается с предоставленными options.

Опции передаются как в конструктор net.Socket, так и в метод socket.connect.

Параметр connectListener будет добавлен в качестве слушателя события 'connect' один раз.

Вот пример клиента ранее описанного эхо-сервера:

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) => {
  console.log(data.toString());
  client.end();
});
client.on('end', () => {
  console.log('disconnected from server');
});

Для подключения к сокету /tmp/echo.sock вторая строка будет изменена на

const client = net.connect({path: '/tmp/echo.sock'});

net.connect(path[, connectListener])

Функция-фабрика, которая возвращает новый UNIX net.Socket и автоматически подключается к предоставленному path.

Параметр connectListener будет добавлен в качестве слушателя события 'connect' один раз.

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

Функция-фабрика, которая возвращает новый net.Socket и автоматически подключается к предоставленным port и host.

Если host опущен, будет использовано 'localhost'.

Параметр connectListener будет добавлен в качестве слушателя события 'connect' один раз.

net.createConnection(options[, connectListener])

Функция-фабрика, которая возвращает новый сокет net.Socket и автоматически подключается к предоставленному options.

Параметры передаются как в конструктор net.Socket, так и в метод socket.connect.

Передача timeout в качестве параметра вызовет socket.setTimeout() после создания сокета, но перед подключением.

Параметр connectListener будет добавлен в качестве слушателя события 'connect' один раз.

Ниже приведён пример клиента для эхо-сервера, описанного в разделе net.createServer():

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) => {
  console.log(data.toString());
  client.end();
});
client.on('end', () => {
  console.log('disconnected from server');
});

Для подключения к сокету /tmp/echo.sock достаточно изменить вторую строку на

const client = net.connect({path: '/tmp/echo.sock'});

net.createConnection(path[, connectListener])

Функция-фабрика, которая возвращает новый unix-сокет net.Socket и автоматически подключается к предоставленному path.

Параметр connectListener будет добавлен в качестве слушателя события 'connect' один раз.

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

Функция-фабрика, которая возвращает новый сокет net.Socket и автоматически подключается к предоставленному port и host.

Если host опущено, используется 'localhost'.

Параметр connectListener будет добавлен в качестве слушателя события 'connect' один раз.

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

Создаёт новый сервер. Аргумент connectionListener автоматически устанавливается в качестве слушателя события 'connection'.

options — объект с указанными значениями по умолчанию:

{
  allowHalfOpen: false,
  pauseOnConnect: false
}

• Возвращает: <net.Server>

Если allowHalfOpen равно true, то сокет не будет автоматически отправлять пакет FIN, когда другой конец сокета отправляет пакет FIN. Сокет становится недоступным для чтения, но доступным для записи. Вы должны явно вызвать метод end(). Подробнее см. событие 'end'.

Если pauseOnConnect равно true, то сокет, связанный с каждым входящим подключением, будет приостановлен, и данные не будут читаться из его дескриптора. Это позволяет передавать подключения между процессами без чтения данных исходным процессом. Чтобы начать чтение данных из приостановленного сокета, вызовите resume().

Вот пример эхо-сервера, который прослушивает подключения на порту 8124:

const net = require('net');
const server = net.createServer((c) => {
  // 'connection' listener
  console.log('client connected');
  c.on('end', () => {
    console.log('client disconnected');
  });
  c.write('hello\r\n');
  c.pipe(c);
});
server.on('error', (err) => {
  throw err;
});
server.listen(8124, () => {
  console.log('server bound');
});

Протестировать это можно, используя telnet:

$ telnet localhost 8124

Чтобы прослушивать подключения на сокете /tmp/echo.sock , последнюю строку следует изменить на

server.listen('/tmp/echo.sock', () => {
  console.log('server bound');
});

Используйте nc для подключения к серверу сокета Unix-домена:

$ nc -U /tmp/echo.sock

net.isIP(input)

Проверяет, является ли входное значение IP-адресом. Возвращает 0 для недопустимых строк, 4 для IP-адресов версии 4 и 6 для IP-адресов версии 6.

net.isIPv4(input)

Возвращает true, если входное значение — IP-адрес версии 4, в противном случае — false.

net.isIPv6(input)

Возвращает true, если входное значение — IP-адрес версии 6, в противном случае — false.