Сеть

Модуль node:net предоставляет асинхронный сетевой API для создания TCP-серверов на основе потоков или серверов IPC (net.createServer()) и клиентов (net.createConnection()).

К нему можно получить доступ следующим образом:

import net from 'node:net';

const net = require('node:net');

Поддержка IPC

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

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

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

В Unix локальный домен также известен как домен Unix. Путь представляет собой путь в файловой системе. Если длина пути превышает длину sizeof(sockaddr_un.sun_path), будет вызвана ошибка. Типичные значения — 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'));
jscopy

Класс: 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
jscopy

blockList.rules

• Тип: <string[]>

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

BlockList.isBlockList(value)

• value <any> Любое значение JS
• Возвращает true, если value является net.BlockList.

blockList.fromJSON(value)

const blockList = new net.BlockList();
const data = [
  'Subnet: IPv4 192.168.1.0/24',
  'Address: IPv4 10.0.0.5',
  'Range: IPv4 192.168.2.1-192.168.2.10',
  'Range: IPv4 10.0.0.1-10.0.0.10',
];
blockList.fromJSON(data);
blockList.fromJSON(JSON.stringify(data));
jscopy

• value Blocklist.rules

blockList.toJSON()

• Возвращает Blocklist.rules

Класс: 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>

SocketAddress.parse(input)

• input <string> Входная строка, содержащая IP-адрес и необязательный порт, например 123.1.2.3:1234 или [1::1]:1234.
• Возвращает: <net.SocketAddress> Возвращает SocketAddress, если разбор выполнен успешно. В противном случае возвращает undefined.

Класс: 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());
});
jscopy

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

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.
  • reusePort <boolean> Для TCP-серверов установка reusePort в true позволяет нескольким сокетам на одном хосте привязываться к одному порту. ОС распределяет входящие подключения между прослушивающими сокетами. Этот параметр доступен только на некоторых платформах, например Linux 3.9+, DragonFlyBSD 3.6+, FreeBSD 12.0+, Solaris 11.4 и AIX 7.2.5+. На неподдерживаемых платформах этот параметр вызывает ошибку. По умолчанию: 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,
});
jscopy

Если 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();
jscopy

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>

Когда число соединений достигает порогового значения server.maxConnections:

1. Если процесс не запущен в режиме кластера, Node.js закроет соединение.

2. Если процесс запущен в режиме кластера, Node.js по умолчанию перенаправит соединение другому рабочему процессу. Чтобы вместо этого закрыть соединение, установите для server.dropMaxConnection значение true.

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

server.dropMaxConnection

• Тип: <boolean>

Установите для этого свойства значение true, чтобы начать закрывать соединения, когда их количество достигнет порогового значения server.maxConnections. Эта настройка действует только в режиме кластера.

server.ref()

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

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

server.unref()

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

Вызов unref() для сервера позволит программе завершиться, если этот сервер является единственным активным сервером в системе событий. Если сервер уже был unrefed, повторный вызов 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.
  • blockList <net.BlockList> blockList можно использовать для отключения исходящего доступа к определённым IP-адресам, диапазонам IP-адресов или подсетям IP.
  • fd <number> Если указано, создаётся оболочка для существующего сокета с заданным дескриптором файла; в противном случае создаётся новый сокет.
  • keepAlive <boolean> Если установлено значение true, функция keep-alive включается для сокета сразу после установления соединения, аналогично тому, как это происходит в socket.setKeepAlive(). По умолчанию: false.
  • keepAliveInitialDelay <number> Если указано положительное число, оно задаёт начальную задержку перед отправкой первой keepalive-пробы для бездействующего сокета. По умолчанию: 0.
  • noDelay <boolean> Если установлено значение true, использование алгоритма Нейгла отключается сразу после создания сокета. По умолчанию: false.
  • 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, который можно использовать для уничтожения сокета.
  • typeOfService <number> Начальное значение Type of Service (TOS).
  • 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()

• Возвращает: <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'.
• localAddress <string> Локальный адрес, с которого должен подключиться сокет.
• localPort <number> Локальный порт, с которого должен подключиться сокет.
• lookup <Function> Пользовательская функция lookup. По умолчанию: dns.lookup().
• 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();
});
jscopy

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

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

socket.getTypeOfService()

• Возвращает: <integer> Текущее значение TOS.

Возвращает для этого сокета текущее значение поля Type of Service (TOS) для пакетов IPv4 или Traffic Class для пакетов IPv6.

setTypeOfService() можно вызвать до подключения сокета; значение будет сохранено в кэше и применено после установления подключения. getTypeOfService() вернет текущее заданное значение, даже если подключение еще не установлено.

На некоторых платформах (например, Linux) определенные биты TOS/ECN могут маскироваться или игнорироваться, а поведение может различаться для IPv4, IPv6 и сокетов с поддержкой обоих стеков. Вызывающим сторонам следует проверять особенности реализации на конкретной платформе.

socket.setTypeOfService(tos)

• tos <integer> Задаваемое значение TOS (0–255).
• Возвращает: <net.Socket> Сам сокет.

Задает для отправляемых этим сокетом пакетов IPv4 поле Type of Service (TOS), а для пакетов IPv6 — поле Traffic Class. Это можно использовать для приоритизации сетевого трафика.

setTypeOfService() можно вызвать до подключения сокета; значение будет сохранено в кэше и применено после установления подключения. getTypeOfService() вернет текущее заданное значение, даже если подключение еще не установлено.

На некоторых платформах (например, Linux) определенные биты TOS/ECN могут маскироваться или игнорироваться, а поведение может различаться для IPv4, IPv6 и сокетов с поддержкой обоих стеков. Вызывающим сторонам следует проверять особенности реализации на конкретной платформе.

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 будет выполнен после окончательной записи данных, которая может произойти не сразу.

Дополнительную информацию см. в описании метода Writable потока write().

socket.readyState

• Тип: <string>

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

• Если поток подключается, socket.readyState имеет значение opening.
• Если поток доступен для чтения и записи, его значение — open.
• Если поток доступен для чтения, но не для записи, его значение — readOnly.
• Если поток недоступен ни для чтения, ни для записи, его значение — writeOnly.

net.connect()

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

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

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

net.connect(options[, connectListener])

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

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

net.connect(path[, connectListener])

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

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

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

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

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

net.createConnection()

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

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

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

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

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

net.createConnection(options[, connectListener])

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

Ниже приведён пример клиента, использующего параметры 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> Если задано положительное число, оно определяет начальную задержку перед отправкой первого зонда поддержания активности по неактивному сокету. По умолчанию: 0.
  • noDelay <boolean> Если установлено значение true, сразу после получения нового входящего соединения отключается алгоритм Нейгла. По умолчанию: false.
  • pauseOnConnect <boolean> Указывает, следует ли приостанавливать сокет для входящих соединений. По умолчанию: false.
  • blockList <net.BlockList> blockList можно использовать для блокировки входящего доступа с определённых IP-адресов, диапазонов IP-адресов или IP-подсетей. Это не работает, если сервер находится за обратным прокси-сервером, NAT и т. п., поскольку с адресом в списке блокировки сравнивается адрес прокси-сервера или адрес, указанный NAT.

• 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
bashcopy

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

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

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

nc -U /tmp/echo.sock
bashcopy

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). Начальное значение по умолчанию — 500 или значение, указанное с помощью параметра командной строки --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
jscopy

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
jscopy

net.isIPv6(input)

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

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

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