Поддержка 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 <string> | <net.SocketAddress> IPv4- или IPv6-адрес.
• type <string> Значение 'ipv4' или 'ipv6'. По умолчанию: 'ipv4'.

Добавляет правило, блокирующее указанный IP-адрес.

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

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

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

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

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

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

blockList.check(address[, type])

• address <string> | <net.SocketAddress> Проверяемый IP-адрес
• type <string> Значение 'ipv4' или 'ipv6'. По умолчанию: 'ipv4'.
• Возвращает: <boolean>

Возвращает 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

• Тип: <string[]>

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

Класс: net.SocketAddress

new net.SocketAddress([options])

• options <Object>
  • address <string> Сетевой адрес в виде строки IPv4 или IPv6. По умолчанию: '127.0.0.1', если family — 'ipv4'; '::', если family — 'ipv6'.
  • family <string> Одно из значений: 'ipv4' или 'ipv6'. По умолчанию: 'ipv4'.
  • flowlabel <number> Метка потока IPv6, используемая только если family — 'ipv6'.
  • port <number> IP-порт.

socketaddress.address

• Тип <string>

socketaddress.family

• Тип <string> Значение 'ipv4' или 'ipv6'.

socketaddress.flowlabel

• Тип <number>

socketaddress.port

• Тип <number>

Класс: net.Server

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

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

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

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

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

Событие: 'close'

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

Событие: 'connection'

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

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

Событие: 'error'

• <Error>

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

Событие: 'listening'

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

Событие: 'drop'

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

• data <Object> Аргумент, передаваемый обработчику события.
  • localAddress <string> Локальный адрес.
  • localPort <number> Локальный порт.
  • localFamily <string> Локальное семейство адресов.
  • remoteAddress <string> Удалённый адрес.
  • remotePort <number> Удалённый порт.
  • remoteFamily <string> Семейство IP удалённого узла. 'IPv4' или 'IPv6'.

server.address()

• Возвращает: <Object> | <string> | <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 <Function> Вызывается при закрытии сервера.
• Возвращает: <net.Server>

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

server[Symbol.asyncDispose]()

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

server.getConnections(callback)

• callback <Function>
• Возвращает: <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 <Object>
• backlog <number> Общий параметр функций server.listen()
• callback <Function>
• Возвращает: <net.Server>

Запускает сервер, ожидающий соединений на заданном 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 <Object> Доступные параметры:
  • allowHalfOpen <boolean> Если задано значение false, сокет автоматически завершит записываемую сторону, когда завершится читаемая сторона. Подробности см. в разделе net.createServer() и описании события 'end'. По умолчанию: false.
  • fd <number> Если указан, существующий сокет будет обёрнут с использованием заданного файлового дескриптора; в противном случае будет создан новый сокет.
  • onread <Object> Если указан, входящие данные сохраняются в одном buffer и передаются указанному callback при поступлении данных в сокет. При этом потоковая передача не будет предоставлять никаких данных. Сокет будет, как обычно, генерировать такие события, как 'error', 'end' и 'close'. Такие методы, как pause() и resume(), также будут работать ожидаемым образом.
    • buffer <Buffer> | <Uint8Array> | <Function> Повторно используемый блок памяти для хранения входящих данных либо функция, возвращающая такой блок.
    • callback <Function> Эта функция вызывается для каждого фрагмента входящих данных. Ей передаются два аргумента: количество байтов, записанных в buffer, и ссылка на buffer. Верните из этой функции false, чтобы неявно выполнить pause() сокета. Эта функция будет выполняться в глобальном контексте.
  • readable <boolean> Разрешает чтение из сокета, если передан fd; в противном случае игнорируется. По умолчанию: false.
  • signal <AbortSignal> Сигнал Abort, который можно использовать для уничтожения сокета.
  • 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().

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

Событие: 'drain'

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

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

Событие: 'end'

Генерируется, когда другая сторона сокета сигнализирует о завершении передачи данных, тем самым завершая читаемую сторону сокета.

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

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

• Возвращает: <Object>

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

socket.autoSelectFamilyAttemptedAddresses

• <string[]>

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

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

socket.bufferSize

• <integer>

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

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

Из-за такой внутренней буферизации объём используемой памяти может увеличиваться. Пользователям, у которых наблюдается значительное или постоянно растущее значение bufferSize, следует попытаться регулировать потоки данных в программе с помощью методов socket.pause() и socket.resume().

socket.bytesRead

• <integer>

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

socket.bytesWritten

• <integer>

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

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 <Object>
• connectListener <Function> Общий параметр методов socket.connect(). Однократно добавляется в качестве обработчика события 'connect'.
• Возвращает: <net.Socket> Сам сокет.

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

Для 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> Если задано положительное число, оно устанавливает начальную задержку перед отправкой первой пробы keep-alive для простаивающего сокета. По умолчанию: 0.
• localAddress <string> Локальный адрес, с которого должен подключаться сокет.
• localPort <number> Локальный порт, с которого должен подключаться сокет.
• lookup <Function> Пользовательская функция lookup. По умолчанию: dns.lookup().
• noDelay <boolean> Если задано значение true, сразу после установления соединения для сокета отключается алгоритм Nagle. По умолчанию: false.
• port <number> Обязательный параметр. Порт, к которому должен подключиться сокет.

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

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

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 <string> | <Buffer> | <Uint8Array>
• encoding <string> Используется только, когда данные имеют тип string. По умолчанию: 'utf8'.
• callback <Function> Необязательная функция обратного вызова, вызываемая после завершения работы сокета.
• Возвращает: <net.Socket> Сам сокет.

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

Дополнительные сведения см. в разделе writable.end().

socket.localAddress

• <string>

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

socket.localPort

• <integer>

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

socket.localFamily

• <string>

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

socket.pause()

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

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

socket.pending

• <boolean>

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

socket.ref()

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

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

socket.remoteAddress

• <string>

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

socket.remoteFamily

• <string>

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

socket.remotePort

• <integer>

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

socket.resetAndDestroy()

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

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

socket.resume()

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

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

socket.setEncoding([encoding])

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

Задаёт кодировку сокета как потока для чтения. Дополнительные сведения см. в разделе readable.setEncoding().

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

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

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

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

Включение функции поддержания соединения задаёт следующие параметры сокета:

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

socket.setNoDelay([noDelay])

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

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

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

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

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

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

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

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

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

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

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

Дополнительные сведения см. в описании метода write() потока Writable.

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 <Object> Обязательный параметр. Передаётся как в вызов new net.Socket([options]), так и в метод socket.connect(options[, connectListener]).
• connectListener <Function> Общий параметр функций net.createConnection(). Если он указан, будет однократно добавлен как обработчик события 'connect' на возвращённом сокете.
• Возвращает: <net.Socket> Созданный сокет, используемый для запуска соединения.

Доступные параметры см. в разделах new net.Socket([options]) и socket.connect(options[, connectListener]).

Дополнительные параметры:

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

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

import net from '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');
});

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');
});

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

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

Ниже приведён пример клиента, использующего параметры port и onread. В этом случае параметр onread будет использоваться только для вызова new net.Socket([options]), а параметр port — для вызова socket.connect(options[, connectListener]).

import net from 'node:net';
import { Buffer } from 'node:buffer';
net.createConnection({
  port: 8124,
  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));
    },
  },
});

const net = require('node:net');
net.createConnection({
  port: 8124,
  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));
    },
  },
});

net.createConnection(path[, connectListener])

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

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

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

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

• port <number> Порт, к которому должен подключиться сокет. Передаётся в socket.connect(port[, host][, connectListener]).
• host <string> Узел, к которому должен подключиться сокет. Передаётся в socket.connect(port[, host][, connectListener]). По умолчанию: 'localhost'.
• connectListener <Function> Общий параметр функций 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 <Object>

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

• connectionListener <Function> Автоматически устанавливается как обработчик события '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().

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

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

import net from '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');
});

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');
});

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

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