Перейти к содержанию

Net

v18.x.x

Стабильность: 2 – Стабильная

АПИ является удовлетворительным. Совместимость с NPM имеет высший приоритет и не будет нарушена кроме случаев явной необходимости.

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

Доступ к нему можно получить с помощью:

1
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) - 1. Типичные значения - 107 байт в Linux и 103 байта в macOS. Если абстракция API Node.js создает сокет домена Unix, она также развязывает сокет домена Unix. Например, net.createServer() может создать сокет домена Unix, а server.close() отсоединит его. Но если пользователь создает сокет домена Unix вне этих абстракций, ему придется удалить его. То же самое относится к случаям, когда API Node.js создает сокет домена Unix, но затем программа аварийно завершается. Короче говоря, сокет домена Unix будет виден в файловой системе и будет существовать до тех пор, пока не будет удален.

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

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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

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.

socketaddress.family.

  • Тип <string> Либо IPv4, либо IPv6.

socketaddress.flowlabel.

socketaddress.port.

Класс: net.Server

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

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

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

Событие: закрытие.

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

Событие: 'connection'

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

Событие: ошибка.

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

Событие: прослушивание.

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

Событие: 'drop'.

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

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

server.address().

  • Возвращает: {Object|string|null}

Возвращает связанный адрес, имя семейства адресов и порт сервера, как сообщает операционная система, если он прослушивает IP-сокет (полезно, чтобы узнать, какой порт был назначен при получении адреса, назначенного ОС): `{ port: 12346, семейство: 'IPv4', адрес: '127.0.

Для сервера, слушающего на сокете pipe или Unix domain, имя возвращается в виде строки.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
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());
});

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

server.close([callback]).

  • callback <Function> Вызывается при закрытии сервера.
  • Возвращает: {net.Server}

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

server.getConnections(callback).

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

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

Callback должен принимать два аргумента err и count.

server.listen().

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

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

Эта функция является асинхронной. Когда сервер начинает прослушивать, будет выдано событие '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. Одним из способов решения этой проблемы может быть повторная попытка через определенное время:

1
2
3
4
5
6
7
8
9
server.on('error', (e) => {
    if (e.code === 'EADDRINUSE') {
        console.error('Address in use, retrying...');
        setTimeout(() => {
            server.close();
            server.listen(PORT, HOST);
        }, 1000);
    }
});

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

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

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

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

server.listen(options[, callback]).

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

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

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

1
2
3
4
5
server.listen({
    host: 'localhost',
    port: 80,
    exclusive: true,
});

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

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

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

1
2
3
4
5
6
7
8
const controller = new AbortController();
server.listen({
    host: 'localhost',
    port: 80,
    signal: controller.signal,
});
// Later, when you want to close the server.
controller.abort();

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

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

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

Запускает 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

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

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

server.ref().

  • Возвращает: {net.Server}.

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

server.unref()

  • Возвращает: {net.Server}.

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

Класс: net.Socket.

  • Расширяет: {stream.Duplex}

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

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

Он также может быть создан Node.js и передан пользователю, когда соединение r

new net.Socket([options]).

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

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

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

Событие: закрытие

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

Выдается после полного закрытия сокета. Аргумент hadError - это булево значение, которое говорит, был ли сокет закрыт из-за ошибки передачи.

Событие: `'connect``.

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

Событие: 'data'

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

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

Событие: `'drain'``.

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

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

Событие: конец.

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

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

Событие: ошибка.

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

Событие: 'lookup'

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

  • err {Error|null} Объект ошибки. См. dns.lookup().
  • address <string> IP-адрес.
  • family <number> | <null> Тип адреса. См. [dns.lookup()](dns.md#dnslookuphostname-optio

Событие: готово.

Возникает, когда сокет готов к использованию.

Срабатывает сразу после 'connect'.

Событие: 'timeout'.

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

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

socket.address().

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

`socket.autoSelectFamilyAttemptedAddresses

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

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

socket.bufferSize.

Стабильность: 0 – устарело или набрало много негативных отзывов

Вместо этого используйте writable.writableLength.

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

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

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

socket.bytesRead

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

socket.bytesWritten.

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

socket.connect().

Инициирует соединение на заданном сокете.

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

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

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

socket.connect(options[, connectListener]).

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

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

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

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

Для IPC соединений, доступными опциями являются:

Для обоих типов доступные опции включают:

  • onread <Object> Если указано, входящие данные хранятся в одном буфере и передаются в указанный обратный вызов, когда данные поступают на сокет. Это приведет к тому, что функциональность потоковой передачи не будет предоставлять никаких данных. Сокет будет выдавать события типа ошибка, конец и закрытие как обычно. Такие методы, как pause() и resume(), также будут вести себя так, как ожидается.
    • buffer {Buffer|Uint8Array|Function} Либо многократно используемый кусок памяти для хранения входящих данных, либо функция, которая их возвращает.
    • callback <Function> Эта функция вызывается для каждого куска входящих данных. Ей передаются два аргумента: количество байт, записанных в buffer, и ссылка на buffer. Возврат false из этой функции позволяет неявно pause() сокета. Эта функция будет выполняться в глобальном контексте.

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

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

socket.connect(path[, connectListener]).

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

Псевдоним для socket.connect(options[, connectListener]), вызываемого с {путь: 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

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

socket.destroy([error]).

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

Подробности смотрите в 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.

Строковое представление локального IP-адреса, по которому подключается удаленный клиент. Для

socket.localPort

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

socket.localFamily

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

socket.pause().

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

socket.pending

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

socket.ref().

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

socket.remoteAddress

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

socket.remoteFamily

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

socket.remotePort

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

socket.resetAndDestroy().

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

socket.resume().

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

socket.setEncoding([encoding])

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

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

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

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

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

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

  • SO_KEEPALIVE=1
  • TCP_KEEPIDLE=initialDelay.
  • TCP_KEEPINTVL=1

socket.setNoDelay([noDelay])

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

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

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

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

socket.setTimeout(timeout[, callback]).

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

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

1
2
3
4
5
socket.setTimeout(3000);
socket.on('timeout', () => {
    console.log('socket timeout');
    socket.end();
});

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

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

socket.timeout

  • {number|undefined}

Таймаут сокета в миллисекундах, установленный socket.setTimeout(). Это undefined, если таймаут не был установлен.

socket.unref().

Вызов 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 stream write().

socket.readyState

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

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

net.connect().

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

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

net.connect(options[, connectListener]).

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

net.connect(path[, connectListener]).

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

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

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

net.createConnection().

Фабрика

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

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

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

net.createConnection(options[, connectListener]).

Доступные опции см. в new net.Socket([options]) и socket.connect(options[, connectListener]).

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
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:

1
2
3
const client = net.createConnection({
    path: '/tmp/echo.sock',
});

net.createConnection(path[, connectListener]).

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

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

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

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

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

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

  • options <Object>

    • allowHalfOpen <boolean> Если установлено значение false, то сокет будет автоматически завершать доступную для записи сторону, когда заканчивается доступная для чтения сторона. По умолчанию: false.
    • pauseOnConnect <boolean> Указывает, должен ли сокет приостанавливаться при входящих соединениях. По умолчанию: false.
    • noDelay <boolean> Если установлено значение true, то отключает использование алгоритма Нагла сразу после получения нового входящего соединения. По умолчанию: false.
    • keepAlive <boolean> Если установлено значение true, это включает функцию keep-alive на сокете сразу после получения нового входящего соединения, аналогично тому, как это делается в socket.setKeepAlive([enable][, initialDelay]). По умолчанию: false.
    • keepAliveInitialDelay <number> Если установлено положительное число

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

  • Возвращает: {net.Server}

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

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

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
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:

1
$ telnet localhost 8124

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

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

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

1
$ nc -U /tmp/echo.sock

net.getDefaultAutoSelectFamily().

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

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

net.setDefaultAutoSelectFamily(value).

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

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

net.getDefaultAutoSelectFamilyAttemptTimeout().

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

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

net.setDefaultAutoSelectFamilyAttemptTimeout(value).

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

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

net.isIP(input)

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

1
2
3
4
5
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

net.isIPv4(input)

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

1
2
3
4
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

net.isIPv6(input)

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

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