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

Модуль 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()

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

Пример:

var 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])

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

server.connections

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

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

server.getConnections(callback)

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

Обратный вызов должен принимать два аргумента err и count.

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

• handle <Объект>
• backlog <Число>
• callback <Функция>

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

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

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

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

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

server.listen(options[, callback])

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

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

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

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

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

• path <Строка>
• backlog <Число>
• callback <Функция>

Запускает локальный сокет-сервер, прослушивающий соединения на указанном 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([port][, hostname][, backlog][, callback])

Начинает принимать соединения на указанном 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.maxConnections

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

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

server.ref()

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

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

server.unref()

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

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

Класс: 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, см. createServer() и событие 'end'.

net.Socket экземпляры — это EventEmitter с указанными событиями:

Событие: 'close'

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

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

Событие: 'connect'

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

Событие: 'data'

• <Буфер>

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

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

Событие: 'drain'

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

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

Событие: 'end'

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

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

Событие: 'error'

• <Ошибка>

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

Событие: 'lookup'

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

• err <Ошибка> | <Null> Объект ошибки. См. dns.lookup().
• address <Строка> IP-адрес.
• family <Строка> | <Null> Тип адреса. См. dns.lookup().

Событие: '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.

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

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

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

Обычно этот метод не требуется, поскольку 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}.

socket.destroy()

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

socket.destroyed

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

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

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

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

socket.localAddress

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

socket.localPort

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

socket.pause()

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

socket.ref()

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

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

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])

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

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

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

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

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

socket.setNoDelay([noDelay])

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

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

socket.setTimeout(timeout[, callback])

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

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

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

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

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

socket.unref()

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

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

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.

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

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

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
}

Если 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.