Поддержка 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-доменный сокет, она также удалит его. Например, 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> 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> Сеть 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 <число> Номер порта.

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

Если 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 <string> Путь, к которому должен прослушивать сервер. См. Идентификация путей для IPC-соединений.
• backlog <number> Общий параметр функций server.listen().
• callback <Function>.
• Возвращает: <net.Server>

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

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

• port <number>
• host <string>
• backlog <number> Общий параметр функций server.listen().
• callback <Function>.
• Возвращает: <net.Server>

Запустить 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

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

server.maxConnections

• <integer>

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

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

server.ref()

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

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

server.unref()

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

Вызов 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 <Объект> Доступные параметры:
  • allowHalfOpen <boolean> Если установлено в false, сокет автоматически завершит сторону записи при завершении стороны чтения. См. net.createServer() и событие 'end' для получения подробностей. По умолчанию: false.
  • fd <число> Если указано, оберните существующий сокет с заданным дескриптором файла, в противном случае будет создан новый сокет.
  • 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 <строка> IP-адрес, к которому пытается подключиться сокет.
• port <число> Порт, к которому пытается подключиться сокет.
• family <число> Семейство IP. Может быть 6 для IPv6 или 4 для IPv4.

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

Событие: 'connectionAttemptFailed'

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

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

Событие: 'connectionAttemptTimeout'

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

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

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

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

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

socket.connect(options[, connectListener])

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

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

Для TCP-соединений доступны options:

• autoSelectFamily <boolean>: Если установлено в true, это включает алгоритм автоматического определения семейства, который приблизительно реализует раздел 5 RFC 8305. Параметр all, переданный в lookup, устанавливается в true, и сокеты пытаются подключиться ко всем полученным адресам IPv6 и IPv4 последовательно, пока не будет установлено соединение. Сначала проверяется первый возвращённый адрес AAAA, затем первый возвращённый адрес A, затем второй возвращённый адрес 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 <строка> | <Buffer> | <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 <булево> По умолчанию: false
• initialDelay <число> По умолчанию: 0
• Возвращает: <net.Socket> Сам сокет.

Включает/отключает функцию 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.Socket> Сам сокет.

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

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

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

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

socket.setTimeout(timeout[, callback])

• timeout <число>
• callback <Функция>
• Возвращает: <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

• <число> | <undefined>

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

socket.unref()

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

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

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

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

Отправляет данные по сокету. Второй параметр указывает кодировку в случае со строкой. По умолчанию используется 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.Сокет>

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

net.connect(path[, connectListener])

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

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

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

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

Псевдоним для 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.

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

net.setDefaultAutoSelectFamily(value)

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

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

net.getDefaultAutoSelectFamilyAttemptTimeout()

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

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

net.setDefaultAutoSelectFamilyAttemptTimeout(value)

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

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

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