Поддержка 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 домена будет виден в файловой системе и будет существовать до тех пор, пока не будет удален. В Linux можно использовать абстрактный сокет Unix, добавив \0 в начало пути, например, \0abstract. Путь к абстрактному сокету Unix не виден в файловой системе и исчезнет автоматически, когда все открытые ссылки на сокет будут закрыты.

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

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

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

Класс: net.BlockList

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

blockList.addAddress(address[, type])

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

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

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

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

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

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

• net <строка> | <net.SocketAddress> Сетевой 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 метка потока, используемая только если family равно 'ipv6'.
  • port <число> Номер IP порта.

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.Сервер>

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

Событие: 'close'

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

Событие: 'connection'

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

Издаётся, когда установлено новое соединение. 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.Сервер>

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

server[Symbol.asyncDispose]()

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

server.getConnections(callback)

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

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

Обработчик должен принимать два аргумента 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.Сервер>

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

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

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

server.listen(options[, callback])

• options <Объект> Обязательный. Поддерживает следующие свойства:
  • backlog <число> Общий параметр функций server.listen().
  • exclusive <логическое_значение> По умолчанию: false
  • host <строка>
  • ipv6Only <логическое_значение> Для TCP-серверов, установка ipv6Only в true отключит поддержку двойного стека, т.е. привязка к хосту :: не заставит 0.0.0.0 быть привязанным. По умолчанию: false.
  • path <строка> Будет проигнорировано, если указан параметр port. См. Определение путей для подключений IPC.
  • port <число>
  • readableAll <логическое_значение> Для IPC-серверов делает пайп читаемым для всех пользователей. По умолчанию: false.
  • signal <AbortSignal> AbortSignal, который может быть использован для закрытия сервера прослушивания.
  • writableAll <логическое_значение> Для IPC-серверов делает пайп записываемым для всех пользователей. По умолчанию: false.
• 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 и базовый обработчик совместно используется, возможно, что несколько рабочих процессов запросят обработчик с различными значениями backlog. В этом случае будет использоваться первый 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-адреса (::) может заставить сервер также прослушивать неопределённый 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 <Object> Доступные параметры:
  • allowHalfOpen <boolean> Если установлено значение false, сокет автоматически завершит запись, когда закончится чтение. Подробнее см. net.createServer() и событие 'end'. По умолчанию: false.
  • fd <number> Если указано, сокет будет обернут вокруг существующего сокета с указанным дескриптором файла, иначе будет создан новый сокет.
  • readable <boolean> Разрешить чтение из сокета, когда передан fd, в противном случае игнорируется. По умолчанию: false.
  • signal <AbortSignal> Сигнал прерывания, который может быть использован для уничтожения сокета.
  • writable <boolean> Разрешить запись в сокет, когда передан fd, в противном случае игнорируется. По умолчанию: false.
• Возвращает: <net.Socket>

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

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

Событие: 'close'

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

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

Событие: 'connect'

Издаётся, когда подключение к сокету успешно установлено. См. net.createConnection().

Событие: 'connectionAttempt'

• ip <string> IP-адрес, к которому пытается подключиться сокет.
• port <number> Порт, к которому пытается подключиться сокет.
• family <number> Семейство IP-адреса. Может быть 6 для IPv6 или 4 для IPv4.

Издаётся при начале новой попытки подключения. Может быть издано несколько раз, если алгоритм автоматического выбора семейства включён в socket.connect(options).

Событие: 'connectionAttemptFailed'

• ip <string> IP-адрес, к которому пытался подключиться сокет.
• port <number> Порт, к которому пытался подключиться сокет.
• family <number> Семейство IP-адреса. Может быть 6 для IPv6 или 4 для IPv4.
• error <Error> Ошибка, связанная с неудачей.

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

Событие: 'connectionAttemptTimeout'

• ip <string> IP-адрес, к которому пытался подключиться сокет.
• port <number> Порт, к которому пытался подключиться сокет.
• family <number> Семейство IP-адреса. Может быть 6 для IPv6 или 4 для IPv4.

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

Событие: 'data'

• <Buffer> | <string>

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

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

Событие: 'drain'

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

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

Событие: 'end'

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

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

Событие: 'error'

• <Error>

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

Событие: 'lookup'

Издаётся после разрешения имени хоста, но до подключения. Не применимо к Unix-сокеттам.

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

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

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

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

socket.connect(options[, connectListener])

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

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

Для подключений TCP доступны следующие options:

• autoSelectFamily <boolean>: Если установлено в true, это включает алгоритм автоматического определения семейства, который приблизительно реализует раздел 5 RFC 8305. Параметр all, передаваемый в lookup, устанавливается в true, и сокеты пытаются подключиться ко всем полученным адресам IPv6 и IPv4 последовательно до тех пор, пока не будет установлено подключение. Сначала пробуется первый возвращенный адрес AAAA, затем первый возвращенный адрес А, затем второй возвращенный адрес AAAA и так далее. Каждая попытка подключения (кроме последней) получает указанное время, заданное параметром autoSelectFamilyAttemptTimeout, перед истечением времени ожидания и переходом к следующему адресу. Игнорируется, если параметр family не равен 0 или если localAddress установлено. Ошибки подключения не генерируются, если хотя бы одно подключение успешно. Если все попытки подключения завершаются неудачей, генерируется одиночное AggregateError со всеми неудачными попытками. По умолчанию: net.getDefaultAutoSelectFamily().
• autoSelectFamilyAttemptTimeout <number>: Время в миллисекундах ожидания завершения попытки подключения перед переходом к следующему адресу при использовании параметра autoSelectFamily. Если значение равно положительному целому числу меньше, чем 10, вместо него будет использоваться значение 10. По умолчанию: net.getDefaultAutoSelectFamilyAttemptTimeout().
• family <number>: Версия стека IP. Должно быть 4, 6, или 0. Значение 0 указывает, что разрешены как IPv4, так и IPv6 адреса. По умолчанию: 0.
• hints <number> Дополнительные dns.lookup() подсказки.
• host <string> Хост, к которому должен подключиться сокет. По умолчанию: 'localhost'.
• keepAlive <boolean> Если установлено в true, это включает функциональность keep-alive для сокета сразу после установления подключения, аналогично тому, что выполняется в socket.setKeepAlive(). По умолчанию: false.
• keepAliveInitialDelay <number> Если установлено в положительное число, это задает начальную задержку перед отправкой первого запроса keepalive для сокета в состоянии ожидания. По умолчанию: 0.
• localAddress <string> Локальный адрес, с которого должен подключиться сокет.
• localPort <number> Локальный порт, с которого должен подключиться сокет.
• lookup <Function> Пользовательская функция поиска. По умолчанию: dns.lookup().
• noDelay <boolean> Если установлено в true, это отключает использование алгоритма Nagle сразу после установления сокета. По умолчанию: false.
• port <number> Требуемый порт, к которому должен подключиться сокет.

Для подключений IPC доступны options:

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

Для обоих типов доступны options:

• onread <Object> Если указано, входящие данные хранятся в одном buffer и передаются в предоставленную callback при поступлении данных на сокет. Это приведет к тому, что функциональность потоковой передачи не предоставит никаких данных. Сокет будет генерировать события, такие как 'error', 'end', и 'close', как обычно. Методы, такие как pause() и resume(), также будут работать как ожидается.
  • buffer <Buffer> | <Uint8Array> | <Function> Либо повторно используемый блок памяти для хранения входящих данных, либо функция, возвращающая такой блок.
  • callback <Function> Эта функция вызывается для каждого блока входящих данных. Ей передаются два аргумента: количество байтов, записанных в 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 <Function> Общий параметр методов socket.connect(). Будет добавлен как обработчик события 'connect' один раз.
• Возвращает: <net.Socket> Сам сокет.

Инициализация подключения IPC к заданному сокету.

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

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

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

Инициализация TCP-подключения к заданному сокету.

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

socket.connecting

• <boolean>

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

socket.destroy([error])

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

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

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

socket.destroyed

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

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

socket.destroySoon()

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

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

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

Закрывает сокет наполовину. Т.е., отправляет пакет 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.Сокет> Сам сокет.

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

socket.pending

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

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

socket.ref()

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

Противоположность unref(), вызов ref() на ранее unref сокете не позволит программе выйти, если это единственный оставшийся сокет (поведение по умолчанию). Если сокет ref , вызов 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.Сокет>

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

socket.resume()

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

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

socket.setEncoding([encoding])

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

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

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

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

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

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

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

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

socket.setNoDelay([noDelay])

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

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

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

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

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

socket.setTimeout(timeout[, callback])

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

Устанавливает таймаут сокета через 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

• <число> | <неопределённое>

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

socket.unref()

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

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

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

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

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

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

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

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

socket.readyState

• <строка>

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

• Если поток подключается, то 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 <Объект>
• connectListener <Функция>
• Возвращает: <net.Socket>

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

net.connect(path[, connectListener])

• path <строка>
• connectListener <Функция>
• Возвращает: <net.Socket>

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

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

• port <число>
• host <строка>
• connectListener <Функция>
• Возвращает: <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().
  • keepAlive <логическое> Если установлено в true, то это активирует функцию keep-alive на сокете сразу после получения нового входящего соединения, аналогично тому, что выполняется в socket.setKeepAlive(). По умолчанию: false.
  • keepAliveInitialDelay <число> Если установлено положительным числом, устанавливает начальную задержку перед отправкой первого запроса keepalive на неактивном сокете. По умолчанию: 0.
  • noDelay <логическое> Если установлено в true, то отключает алгоритм Nagle сразу после получения нового входящего соединения. По умолчанию: false.
  • pauseOnConnect <логическое> Указывает, следует ли приостановить сокет при входящих соединениях. По умолчанию: false.

• 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). Начальное значение по умолчанию равно true, если не задан параметр командной строки --no-network-family-autoselection.

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

net.setDefaultAutoSelectFamily(value)

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

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

net.getDefaultAutoSelectFamilyAttemptTimeout()

Получает текущее значение по умолчанию для параметра autoSelectFamilyAttemptTimeout у socket.connect(options). Начальное значение по умолчанию равно 250 или значению, указанному в параметре командной строки --network-family-autoselection-attempt-timeout.

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

net.setDefaultAutoSelectFamilyAttemptTimeout(value)

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

• value <число> Новое значение по умолчанию, которое должно быть положительным числом. Если число меньше 10, используется значение 10 вместо него. Начальное значение по умолчанию равно 250 или значению, указанному в параметре командной строки --network-family-autoselection-attempt-timeout.

net.isIP(input)

• input <строка>
• Возвращает: <целое число>

Возвращает 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 <строка>
• Возвращает: <булево>

Возвращает 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 <строка>
• Возвращает: <булево>

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

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