Поддержка IPC

Модуль node:net поддерживает IPC с именованными каналами на Windows и сокетами Unix-домена на других операционных системах.

Определение путей для подключений IPC

net.connect(), net.createConnection(), server.listen() и socket.connect() принимают параметр path, чтобы определить конечные точки IPC.

В Unix локальный домен также известен как домен Unix. Путь — это путь к файлу в файловой системе. Он усекается до длины, зависящей от операционной системы, sizeof(sockaddr_un.sun_path) - 1. Типичные значения — 107 байт в Linux и 103 байта в macOS. Если абстракция API Node.js создаёт сокет Unix-домена, она также удалит сокет Unix-домена. Например, net.createServer() может создать сокет Unix-домена, а server.close() удалит его. Но если пользователь создаёт сокет Unix-домена вне этих абстракций, пользователь должен удалить его. То же самое относится к случаям, когда API Node.js создаёт сокет Unix-домена, но программа затем аварийно завершается. Короче говоря, сокет Unix-домена будет виден в файловой системе и будет существовать до его удаления.

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

Для экранирования строк JavaScript пути должны быть указаны с дополнительным экранированием обратных слэшей, например:

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

Класс: net.BlockList

Объект BlockList можно использовать с некоторыми сетевыми API для задания правил по отключению входящего или исходящего доступа к определённым IP-адресам, диапазонам IP-адресов или подсетям.

blockList.addAddress(address[, type])

• address <строка> | <net.SocketAddress> IP-адрес IPv4 или IPv6.
• type <строка> Либо 'ipv4' или 'ipv6'. По умолчанию: 'ipv4'.

Добавляет правило для блокирования указанного IP-адреса.

blockList.addRange(start, end[, type])

• start <строка> | <net.SocketAddress> Начальный IP-адрес IPv4 или IPv6 в диапазоне.
• end <строка> | <net.SocketAddress> Конечный IP-адрес IPv4 или IPv6 в диапазоне.
• type <строка> Либо 'ipv4' или 'ipv6'. По умолчанию: 'ipv4'.

Добавляет правило для блокирования диапазона IP-адресов от start (включительно) до end (включительно).

blockList.addSubnet(net, prefix[, type])

• net <строка> | <net.SocketAddress> IP-адрес сети IPv4 или IPv6.
• prefix <число> Количество битов префикса CIDR. Для IPv4 это значение должно быть от 0 до 32. Для IPv6 это значение должно быть от 0 до 128.
• type <строка> Либо 'ipv4' или 'ipv6'. По умолчанию: 'ipv4'.

Добавляет правило для блокирования диапазона IP-адресов, заданных как маска подсети.

blockList.check(address[, type])

• address <строка> | <net.SocketAddress> IP-адрес для проверки
• type <строка> Либо 'ipv4' или 'ipv6'. По умолчанию: 'ipv4'.
• Возвращает: <логическое значение>

Возвращает true если заданный IP-адрес соответствует какому-либо из правил, добавленных в BlockList.

const blockList = new net.BlockList();
blockList.addAddress('123.123.123.123');
blockList.addRange('10.0.0.1', '10.0.0.10');
blockList.addSubnet('8592:757c:efae:4e45::', 64, 'ipv6');

console.log(blockList.check('123.123.123.123'));  // Prints: true
console.log(blockList.check('10.0.0.3'));  // Prints: true
console.log(blockList.check('222.111.111.222'));  // Prints: false

// IPv6 notation for IPv4 addresses works:
console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // Prints: true
console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // Prints: true copy

blockList.rules

• Тип: <массив строк>

Список правил, добавленных в список блокировок.

Класс: net.SocketAddress

new net.SocketAddress([options])

• options <Объект>
  • address <строка> Сетевой адрес в виде строки IPv4 или IPv6. По умолчанию: '127.0.0.1' если family равен 'ipv4'; '::' если family равен 'ipv6'.
  • family <строка> Одно из 'ipv4' или 'ipv6'. По умолчанию: 'ipv4'.
  • flowlabel <число> Значение IPv6 flow-label, используемое только если family равно 'ipv6'.
  • port <число> Номер порта.

socketaddress.address

• Тип <строка>

socketaddress.family

• Тип <строка> Либо 'ipv4' или 'ipv6'.

socketaddress.flowlabel

• Тип <число>

socketaddress.port

• Тип <число>

Класс: net.Server

• Расширяет: <EventEmitter>

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

new net.Server([options][, connectionListener])

• options <Объект> См. net.createServer([options][, connectionListener]).
• connectionListener <Функция> Автоматически устанавливается как обработчик для события 'connection'.
• Возвращает: <net.Server>

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

Событие: 'close'

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

Событие: 'connection'

• <net.Socket> Объект соединения

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

Событие: 'error'

• <Ошибка>

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

Событие: 'listening'

Выпускается, когда сервер привязан после вызова server.listen().

Событие: 'drop'

Когда количество подключений достигает порога server.maxConnections, сервер отклонит новые подключения и вместо этого выпустит событие 'drop'. Если это сервер TCP, аргумент следующий; в противном случае аргумент undefined.

• data <Объект> Аргумент, переданный обработчику события.
  • localAddress <строка> Местный адрес.
  • localPort <число> Местный порт.
  • localFamily <строка> Местная семья.
  • remoteAddress <строка> Дистанционный адрес.
  • remotePort <число> Дистанционный порт.
  • remoteFamily <строка> Дистанционная IP-семья. 'IPv4' или 'IPv6'.

server.address()

• Возвращает: <Объект> | <строка> | <null>

Возвращает привязанный address, адрес family имя и port сервера, как сообщается операционной системой, если сервер слушает на IP-сокете (полезно для определения назначенного порта при получении адреса, назначенного ОС): { 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 an arbitrary unused port.
server.listen(() => {
  console.log('opened server on', server.address());
}); copy

server.address() возвращает null до выпуска события 'listening' или после вызова server.close().

server.close([callback])

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

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

server[Symbol.asyncDispose]()

Вызывает server.close() и возвращает промис, который выполняется, когда сервер закрыт.

server.getConnections(callback)

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

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

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

server.listen()

Запускает сервер, слушающий подключения. net.Server может быть сервером TCP или IPC, в зависимости от того, что он слушает.

Возможные сигнатуры:

• server.listen(handle[, backlog][, callback])
• server.listen(options[, callback])
• server.listen(path[, backlog][, callback]) для серверов IPC
• server.listen([port[, host[, backlog]]][, callback]) для серверов TCP

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

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

Все сокеты net.Socket установлены в SO_REUSEADDR (см. socket(7) для деталей).

Метод server.listen() может быть вызван повторно только в том случае, если при первом вызове server.listen() произошла ошибка или был вызван server.close(). В противном случае будет брошена ошибка ERR_SERVER_ALREADY_LISTEN.

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

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

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

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

Запускает сервер, слушающий подключения на заданном handle, который уже привязан к порту, сокету Unix-доменной системы или именованному каналу Windows.

Объект handle может быть либо сервером, либо сокетом (любой с базовым членом _handle), либо объектом с членом fd, который является допустимым дескриптором файла.

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

server.listen(options[, callback])

• options <Объект> Обязательно. Поддерживает следующие свойства:
  • port <число>
  • host <строка>
  • path <строка> Будет проигнорировано, если port указано. См. Идентификация путей для подключений IPC.
  • backlog <число> Общий параметр функций server.listen().
  • exclusive <логическое значение> По умолчанию: false
  • readableAll <логическое значение> Для серверов IPC делает канал читаемым для всех пользователей. По умолчанию: false.
  • writableAll <логическое значение> Для серверов IPC делает канал записываемым для всех пользователей. По умолчанию: false.
  • ipv6Only <логическое значение> Для TCP-серверов, установив ipv6Only в true, отключит поддержку двойного стека, т. е. привязка к хосту :: не заставит 0.0.0.0 быть привязанным. По умолчанию: false.
  • signal <AbortSignal> AbortSignal, который может быть использован для закрытия сервера прослушивания.
• callback <Функция> функции.
• Возвращает: <net.Сервер>

Если port указано, оно ведет себя так же, как server.listen([port[, host[, backlog]]][, callback]). В противном случае, если path указано, оно ведет себя так же, как server.listen(path[, backlog][, callback]). Если ни один из них не указан, будет выброшено исключение.

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

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

Когда exclusive равно true и базовый обработчик совместно используется, возможно, что несколько рабочих узлов запросят обработчик с разными значениями backlogs. В этом случае будет использован первый backlog, переданный мастер-процессу.

Запуск сервера IPC как root может привести к тому, что путь к серверу станет недоступным для пользователей без привилегий. Использование readableAll и writableAll сделает сервер доступным для всех пользователей.

Если параметр signal включен, вызов .abort() для соответствующего AbortController аналогичен вызову .close() для сервера:

const controller = new AbortController();
server.listen({
  host: 'localhost',
  port: 80,
  signal: controller.signal,
});
// Later, when you want to close the server.
controller.abort(); copy

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

• path <строка> Путь, к которому должен прослушивать сервер. См. Идентификация путей для подключений IPC.
• backlog <число> Общий параметр функций server.listen().
• callback <Функция>.
• Возвращает: <net.Сервер>

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

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

• port <число>
• host <строка>
• backlog <число> Общий параметр функций server.listen().
• callback <Функция>.
• Возвращает: <net.Сервер>

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

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

Если host опущено, сервер будет принимать подключения по неопределенному IPv6-адресу (::) при наличии IPv6 или неопределенному IPv4-адресу (0.0.0.0) в противном случае.

В большинстве операционных систем, прослушивание по неопределенному IPv6-адресу (::) может привести к тому, что net.Server также будет прослушивать по неопределенному IPv4-адресу (0.0.0.0).

server.listening

• <логическое значение> Указывает, прослушивает ли сервер подключения.

server.maxConnections

• <целое число>

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

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

server.ref()

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

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

server.unref()

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

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

Класс: net.Socket

• Расширяет: <stream.Duplex>

Этот класс представляет собой абстракцию TCP-соккета или потокового IPC-конца (использует именованные каналы на Windows и сокеты доменной Unix в противном случае). Он также является EventEmitter.

Объект net.Socket может быть создан пользователем и использован напрямую для взаимодействия с сервером. Например, он возвращается методом net.createConnection(), позволяя пользователю взаимодействовать с сервером.

Он также может быть создан Node.js и передан пользователю при получении соединения. Например, он передаётся слушателям события 'connection', которое генерируется сервером net.Server, позволяя пользователю взаимодействовать с клиентом.

new net.Socket([options])

• options <Объект> Доступные опции:
  • fd <число> Если указано, используется существующий сокет с заданным дескриптором файла; в противном случае создаётся новый сокет.
  • allowHalfOpen <логическое> Если установлено в false, сокет автоматически завершит запись при завершении чтения. Подробнее см. net.createServer() и событие 'end'. По умолчанию: false.
  • readable <логическое> Разрешить чтение по сокету при передаче fd, в противном случае игнорируется. По умолчанию: false.
  • writable <логическое> Разрешить запись по сокету при передаче fd, в противном случае игнорируется. По умолчанию: false.
  • signal <AbortSignal> Объект отмены, который может быть использован для уничтожения сокета.
• Возвращает: <net.Socket>

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

Созданный сокет может быть либо TCP-соккетом, либо потоковым IPC-концом, в зависимости от того, с чем он connect().

Событие: 'close'

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

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

Событие: 'connect'

Срабатывает при успешном установлении соединения сокета. Смотрите net.createConnection().

Событие: 'data'

• <Буфер> | <строка>

Срабатывает при получении данных. Аргумент data будет Buffer или String. Кодировка данных задаётся методом socket.setEncoding().

Данные будут потеряны, если нет слушателя, когда Socket генерирует событие 'data'.

Событие: 'drain'

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

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

Событие: 'end'

Срабатывает, когда другой конец сокета сигнализирует об окончании передачи, завершая чтение по сокету.

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

Событие: 'error'

• <Ошибка>

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

Событие: 'lookup'

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

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

Событие: 'ready'

Срабатывает, когда сокет готов к использованию.

Вызывается сразу после 'connect'.

Событие: 'timeout'

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

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

socket.address()

• Возвращает: <Объект>

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

socket.autoSelectFamilyAttemptedAddresses

• <массив строк>

Это свойство присутствует только если алгоритм автоматического выбора семейства включён в socket.connect(options), и это массив адресов, которые были попытки.

Каждый адрес — строка в формате $IP:$PORT. Если подключение успешно, последний адрес — адрес, к которому сокет подключён в настоящее время.

socket.bufferSize

• <целое>

Это свойство показывает количество символов, буферизованных для записи. Буфер может содержать строки, длина которых после кодирования ещё неизвестна. Поэтому это число лишь приблизительная оценка количества байтов в буфере.

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

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

socket.bytesRead

• <целое>

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

socket.bytesWritten

• <целое>

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

socket.connect()

Инициализация соединения на заданном сокете.

Возможные сигнатуры:

• socket.connect(options[, connectListener])
• socket.connect(path[, connectListener]) для соединений IPC.
• socket.connect(port[, host][, connectListener]) для соединений TCP.
• Возвращает: <net.Socket> Сам сокет.

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

Эта функция должна использоваться только для повторного подключения сокета после того, как 'close' было выведено, иначе это может привести к неопределенному поведению.

socket.connect(options[, connectListener])

• options <Объект>
• connectListener <Функция> Общий параметр методов socket.connect(). Будет добавлен как слушатель события 'connect' один раз.
• Возвращает: <net.Socket> Сам сокет.

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

Для соединений TCP доступны параметры:

• port <число> Обязательный. Порт, к которому должен подключиться сокет.
• host <строка> Хост, к которому должен подключиться сокет. По умолчанию: 'localhost'.
• localAddress <строка> Местный адрес, с которого должен подключиться сокет.
• localPort <число> Местный порт, с которого должен подключиться сокет.
• family <число>: Версия стека IP. Должно быть 4, 6, или 0 Значение 0 указывает, что разрешены как IPv4, так и IPv6 адреса. По умолчанию: 0.
• hints <число> Необязательные dns.lookup() подсказки.
• lookup <Функция> Пользовательская функция поиска. По умолчанию: dns.lookup().
• noDelay <логическое> Если установлено true, это отключает алгоритм Nagle сразу после установления сокета. По умолчанию: false.
• keepAlive <логическое> Если установлено true, это включает функциональность keep-alive на сокете сразу после установления соединения, аналогично тому, что делается в socket.setKeepAlive([enable][, initialDelay]). По умолчанию: false.
• keepAliveInitialDelay <число> Если установлено положительное число, это устанавливает начальную задержку перед отправкой первого запроса keepalive на неактивном сокете. По умолчанию: 0.
• autoSelectFamily <логическое>: Если установлено true, это включает алгоритм автоматического обнаружения семейства, который слабо реализует раздел 5 RFC 8305. Параметр all переданный в lookup, устанавливается в true, и сокеты пытаются подключиться ко всем полученным IPv6 и IPv4 адресам последовательно, пока не будет установлено соединение. Первый возвращенный AAAA адрес будет опробован первым, затем первый возвращенный A адрес, затем второй возвращенный AAAA адрес и так далее. Каждая попытка подключения получает количество времени, указанное параметром autoSelectFamilyAttemptTimeout перед завершением таймаута и переходом к следующему адресу. Игнорируется, если параметр family не 0 или если localAddress установлено. Ошибки подключения не выводятся, если по крайней мере одно подключение успешно. По умолчанию: изначально false, но может быть изменено во время выполнения с помощью net.setDefaultAutoSelectFamily(value) или через параметр командной строки --enable-network-family-autoselection.
• autoSelectFamilyAttemptTimeout <число>: Количество миллисекунд ожидания завершения попытки подключения перед переходом к следующему адресу при использовании параметра autoSelectFamily. Если установлено положительное целое число меньше 10, то используется значение 10. По умолчанию: изначально 250, но может быть изменено во время выполнения с помощью net.setDefaultAutoSelectFamilyAttemptTimeout(value)

Для соединений IPC доступны параметры:

• path <строка> Обязательный. Путь, к которому должен подключиться клиент. См. Определение путей для соединений IPC. Если задан, TCP-специфические параметры выше игнорируются.

Для обоих типов доступны параметры:

• onread <Объект> Если задан, входящие данные хранятся в одном buffer и передаются предоставленной callback при поступлении данных на сокет. Это приведет к тому, что функция потоковой передачи не предоставит никаких данных. Сокет будет генерировать события, такие как 'error', 'end', и 'close' как обычно. Методы, такие как pause() и resume() также будут работать как ожидается.
  • buffer <Буфер> | <Uint8 массив> | <Функция> Либо повторно используемый блок памяти для хранения входящих данных, либо функция, возвращающая такой блок.
  • callback <Функция> Эта функция вызывается для каждого блока входящих данных. Ей передаются два аргумента: количество байтов, записанных в buffer и ссылка на buffer. Возвращение false из этой функции неявно pause() сокет. Эта функция будет выполнена в глобальном контексте.

Ниже приведен пример клиента, использующего параметр onread:

const net = require('node:net');
net.connect({
  port: 80,
  onread: {
    // Reuses a 4KiB Buffer for every read from the socket.
    buffer: Buffer.alloc(4 * 1024),
    callback: function(nread, buf) {
      // Received data is available in `buf` from 0 to `nread`.
      console.log(buf.toString('utf8', 0, nread));
    },
  },
}); copy

socket.connect(path[, connectListener])

• path <string> Путь, к которому должен подключиться клиент. См. Определение путей для соединений IPC.
• connectListener <Функция> Общий параметр методов socket.connect(). Будет добавлен как обработчик события 'connect' один раз.
• Возвращает: <net.Socket> Сам сокет.

Инициализировать соединение IPC на заданном сокете.

Псевдоним для socket.connect(options[, connectListener]) с вызовом { path: path } в качестве options.

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

• port <число> Порт, к которому должен подключиться клиент.
• host <строка> Хост, к которому должен подключиться клиент.
• connectListener <Функция> Общий параметр методов socket.connect(). Будет добавлен как обработчик события 'connect' один раз.
• Возвращает: <net.Socket> Сам сокет.

Инициализировать TCP-соединение на заданном сокете.

Псевдоним для socket.connect(options[, connectListener]) с вызовом {port: port, host: host} в качестве options.

socket.connecting

• <логическое значение>

Если true, socket.connect(options[, connectListener]) был вызван и ещё не завершен. Он останется true до подключения сокета, затем устанавливается в false и генерируется событие 'connect'. Обратите внимание, что обратный вызов socket.connect(options[, connectListener]) является обработчиком события 'connect'.

socket.destroy([error])

• error <Объект>
• Возвращает: <net.Socket>

Обеспечивает, что больше не происходит операций ввода-вывода на этом сокете. Уничтожает поток и закрывает соединение.

См. writable.destroy() для получения дополнительной информации.

socket.destroyed

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

См. writable.destroyed для получения дополнительной информации.

socket.destroySoon()

Уничтожает сокет после записи всех данных. Если событие 'finish' уже было сгенерировано, сокет уничтожается немедленно. Если сокет всё ещё доступен для записи, он неявно вызывает socket.end().

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

• data <строка> | <Буфер> | <Uint8Array>
• encoding <строка> Используется только тогда, когда данные string. По умолчанию: 'utf8'.
• callback <Функция> Необязательный обратный вызов, когда сокет завершён.
• Возвращает: <net.Socket> Сам сокет.

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

См. writable.end() для получения дополнительной информации.

socket.localAddress

• <строка>

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

socket.localPort

• <целое число>

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

socket.localFamily

• <строка>

Строковое представление семейства локальных IP. 'IPv4' или 'IPv6'.

socket.pause()

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

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

socket.pending

• <логическое значение>

Это true если сокет ещё не подключён, либо потому что .connect() ещё не был вызван, либо потому что он всё ещё в процессе подключения (см. socket.connecting).

socket.ref()

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

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

socket.remoteAddress

• <строка>

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

socket.remoteFamily

• <строка>

Строковое представление семейства удалённых IP. 'IPv4' или 'IPv6'. Значение может быть undefined если сокет разрушен (например, если клиент отключился).

socket.remotePort

• <целое число>

Числовое представление удалённого порта. Например, 80 или 21. Значение может быть undefined если сокет разрушен (например, если клиент отключился).

socket.resetAndDestroy()

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

Закрыть TCP-соединение, отправив пакет RST и уничтожить поток. Если этот TCP-сокет находится в состоянии подключения, он отправит пакет RST и уничтожит этот TCP-сокет после подключения. В противном случае он вызовет socket.destroy с ошибкой ERR_SOCKET_CLOSED . Если это не TCP-сокет (например, пайп), вызов этого метода сразу же выбросит ошибку ERR_INVALID_HANDLE_TYPE.

socket.resume()

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

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

socket.setEncoding([encoding])

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

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

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

• enable <boolean> По умолчанию: false
• initialDelay <number> По умолчанию: 0
• Возвращает: <net.Socket> Сам сокет.

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

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

Включение функциональности keep-alive установит следующие опции сокета:

• SO_KEEPALIVE=1
• TCP_KEEPIDLE=initialDelay
• TCP_KEEPCNT=10
• TCP_KEEPINTVL=1

socket.setNoDelay([noDelay])

• noDelay <boolean> По умолчанию: true
• Возвращает: <net.Socket> Сам сокет.

Включить/выключить использование алгоритма Nagle.

При создании TCP-соединения алгоритм Nagle включён.

Алгоритм Nagle задерживает данные перед их отправкой по сети. Он пытается оптимизировать пропускную способность за счёт задержки.

Передача true для noDelay или отсутствие аргумента отключит алгоритм Nagle для сокета. Передача false для noDelay включит алгоритм Nagle.

socket.setTimeout(timeout[, callback])

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

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

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

socket.setTimeout(3000);
socket.on('timeout', () => {
  console.log('socket timeout');
  socket.end();
}); copy

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

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

socket.timeout

• <number> | <undefined>

Таймаут сокета в миллисекундах, установленный с помощью socket.setTimeout(). Он равен undefined если таймаут не был установлен.

socket.unref()

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

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

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

• data <string> | <Buffer> | <Uint8Array>
• encoding <string> Используется только при передаче данных в виде string. По умолчанию: utf8.
• callback <Function>
• Возвращает: <boolean>

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

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

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

См. метод потока Writable write() для получения дополнительной информации.

socket.readyState

• <string>

Это свойство представляет состояние подключения в виде строки.

• Если поток устанавливает соединение, socket.readyState имеет значение opening.
• Если поток читабелен и записываемый, то он open.
• Если поток читабелен и не записываемый, то он readOnly.
• Если поток не читабелен и не записываемый, то он writeOnly.

net.connect()

Псевдоним для net.createConnection().

Возможные подписи:

• net.connect(options[, connectListener])
• net.connect(path[, connectListener]) для соединений IPC.
• net.connect(port[, host][, connectListener]) для TCP-соединений.

net.connect(options[, connectListener])

• options <Object>
• connectListener <Function>
• Возвращает: <net.Socket>

Псевдоним для net.createConnection(options[, connectListener]).

net.connect(path[, connectListener])

• path <string>
• connectListener <Function>
• Возвращает: <net.Socket>

Псевдоним для net.createConnection(path[, connectListener]).

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

• port <number>
• host <string>
• connectListener <Function>
• Возвращает: <net.Socket>

Псевдоним для net.createConnection(port[, host][, connectListener]).

net.createConnection()

Функция-фабрика, которая создаёт новый net.Socket, немедленно инициирует соединение с socket.connect(), а затем возвращает net.Socket , который начинает соединение.

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

Возможные сигнатуры:

• net.createConnection(options[, connectListener])
• net.createConnection(path[, connectListener]) для соединений IPC.
• net.createConnection(port[, host][, connectListener]) для соединений TCP.

Функция net.connect() является псевдонимом для этой функции.

net.createConnection(options[, connectListener])

• options <Объект> Необходимо. Будет передано как в вызов new net.Socket([options]), так и в метод socket.connect(options[, connectListener]).
• connectListener <Функция> Общий параметр функций net.createConnection(). Если указан, будет добавлен в качестве слушателя события 'connect' на возвращённом сокете один раз.
• Возвращает: <net.Socket> Новый созданный сокет, используемый для начала соединения.

Для доступных опций см. new net.Socket([options]) и socket.connect(options[, connectListener]).

Дополнительные опции:

• timeout <число> Если задано, будет использоваться для вызова socket.setTimeout(timeout) после создания сокета, но до начала соединения.

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

const net = require('node: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');
}); copy

Для подключения к сокету /tmp/echo.sock:

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

net.createConnection(path[, connectListener])

• path <строка> Путь, к которому должен подключиться сокет. Будет передано в socket.connect(path[, connectListener]). См. Определение путей для соединений IPC.
• connectListener <Функция> Общий параметр функций net.createConnection(), слушатель "один раз" для события 'connect' на инициализирующем сокете. Будет передано в socket.connect(path[, connectListener]).
• Возвращает: <net.Socket> Новый созданный сокет, используемый для начала соединения.

Инициализирует соединение IPC.

Эта функция создаёт новый net.Socket со всеми параметрами по умолчанию, немедленно инициирует соединение с socket.connect(path[, connectListener]), а затем возвращает net.Socket , который начинает соединение.

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

• port <число> Порт, к которому должен подключиться сокет. Будет передано в socket.connect(port[, host][, connectListener]).
• host <строка> Хост, к которому должен подключиться сокет. Будет передано в socket.connect(port[, host][, connectListener]). По умолчанию: 'localhost'.
• connectListener <Функция> Общий параметр функций net.createConnection(), слушатель "один раз" для события 'connect' на инициализирующем сокете. Будет передано в socket.connect(port[, host][, connectListener]).
• Возвращает: <net.Socket> Новый созданный сокет, используемый для начала соединения.

Инициализирует соединение TCP.

Эта функция создаёт новый net.Socket со всеми параметрами по умолчанию, немедленно инициирует соединение с socket.connect(port[, host][, connectListener]), а затем возвращает net.Socket , который начинает соединение.

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

• options <Объект>

  • allowHalfOpen <логическое значение> Если установлено в значение false, то сокет автоматически завершит сторону записи, когда завершится сторона чтения. По умолчанию: false.
  • highWaterMark <число> Опционально переопределяет все net.Socket значения readableHighWaterMark и writableHighWaterMark. По умолчанию: См. stream.getDefaultHighWaterMark().
  • pauseOnConnect <логическое значение> Указывает, должен ли сокет приостанавливаться при входящих подключениях. По умолчанию: false.
  • noDelay <логическое значение> Если установлено в true, отключает использование алгоритма Найгла сразу после получения нового входящего подключения. По умолчанию: false.
  • keepAlive <логическое значение> Если установлено в true, включает функцию keep-alive на сокете сразу после получения нового входящего подключения, аналогично тому, что делается в socket.setKeepAlive([enable][, initialDelay]). По умолчанию: false.
  • keepAliveInitialDelay <число> Если установлено в положительное число, задаёт начальную задержку перед отправкой первого запроса keepalive на неактивном сокете. По умолчанию: 0.

• connectionListener <Функция> Автоматически устанавливается в качестве слушателя события 'connection'.

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

Создаёт новый TCP или IPC сервер.

Если allowHalfOpen установлено в true, когда другой конец сокета сигнализирует о завершении передачи, сервер отправит сигнал завершения передачи только при явном вызове socket.end(). Например, в контексте TCP, при получении пакета FIN, пакет FIN отправляется только при явном вызове socket.end(). До этого момента соединение является полузакрытым (нечитаемым, но всё ещё записываемым). См. событие 'end' и RFC 1122 (раздел 4.2.2.13) для получения дополнительной информации.

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

Сервер может быть TCP-сервером или IPC-сервером, в зависимости от того, к чему он listen().

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

const net = require('node: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');
}); copy

Протестируйте это, используя telnet:

$ telnet localhost 8124 copy

Для прослушивания на сокете /tmp/echo.sock:

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

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

$ nc -U /tmp/echo.sock copy

net.getDefaultAutoSelectFamily()

Получает текущее значение по умолчанию для параметра autoSelectFamily в socket.connect(options).

• Возвращает: <boolean> Текущее значение по умолчанию параметра autoSelectFamily.

net.setDefaultAutoSelectFamily(value)

Устанавливает значение по умолчанию для параметра autoSelectFamily в socket.connect(options).

• value <boolean> Новое значение по умолчанию. Начальное значение по умолчанию — false.

net.getDefaultAutoSelectFamilyAttemptTimeout()

Получает текущее значение по умолчанию для параметра autoSelectFamilyAttemptTimeout в socket.connect(options).

• Возвращает: <number> Текущее значение по умолчанию параметра autoSelectFamilyAttemptTimeout.

net.setDefaultAutoSelectFamilyAttemptTimeout(value)

Устанавливает значение по умолчанию для параметра autoSelectFamilyAttemptTimeout в socket.connect(options).

• value <number> Новое значение по умолчанию, которое должно быть положительным числом. Если число меньше 10, используется значение 10. Начальное значение по умолчанию — 250.

net.isIP(input)

• input <string>
• Возвращает: <integer>

Возвращает 6 если input — это IPv6-адрес. Возвращает 4 если input — это IPv4-адрес в точечной десятичной нотации без ведущих нулей. В противном случае возвращает 0.

net.isIP('::1'); // returns 6
net.isIP('127.0.0.1'); // returns 4
net.isIP('127.000.000.001'); // returns 0
net.isIP('127.0.0.1/24'); // returns 0
net.isIP('fhqwhgads'); // returns 0 copy

net.isIPv4(input)

• input <string>
• Возвращает: <boolean>

Возвращает true если input — это IPv4-адрес в точечной десятичной нотации без ведущих нулей. В противном случае возвращает false.

net.isIPv4('127.0.0.1'); // returns true
net.isIPv4('127.000.000.001'); // returns false
net.isIPv4('127.0.0.1/24'); // returns false
net.isIPv4('fhqwhgads'); // returns false copy

net.isIPv6(input)

• input <string>
• Возвращает: <boolean>

Возвращает true если input — это IPv6-адрес. В противном случае возвращает false.

net.isIPv6('::1'); // returns true
net.isIPv6('fhqwhgads'); // returns false copy