Поддержка IPC

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

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

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

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

Класс: net.BlockList

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

blockList.addAddress(address[, type])

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

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

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

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

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

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

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

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

blockList.check(address[, type])

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

Возвращает true , если заданный IP-адрес соответствует одному из правил, добавленных в BlockList.

const blockList = new net.BlockList();
blockList.addAddress('123.123.123.123');
blockList.addRange('10.0.0.1', '10.0.0.10');
blockList.addSubnet('8592:757c:efae:4e45::', 64, 'ipv6');

console.log(blockList.check('123.123.123.123'));  // Prints: true
console.log(blockList.check('10.0.0.3'));  // Prints: true
console.log(blockList.check('222.111.111.222'));  // Prints: false

// IPv6 notation for IPv4 addresses works:
console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // Prints: true
console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // Prints: true

blockList.rules

• Тип: <массив строк>

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

Класс: net.SocketAddress

new net.SocketAddress([options])

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

socketaddress.address

• Тип <строка>

socketaddress.family

• Тип <строка> 'ipv4' или 'ipv6'.

socketaddress.flowlabel

• Тип <число>

socketaddress.port

• Тип <число>

Класс: net.Server

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

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

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

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

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

Событие: 'close'

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

Событие: 'connection'

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

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

Событие: 'error'

• <Ошибка>

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

Событие: 'listening'

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

server.address()

• Возвращает: <Объект> | <строка> | <null>

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

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

const server = net.createServer((socket) => {
  socket.end('goodbye\n');
}).on('error', (err) => {
  // Handle errors here.
  throw err;
});

// Grab an arbitrary unused port.
server.listen(() => {
  console.log('opened server on', server.address());
});

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

server.close([callback])

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

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

server.getConnections(callback)

• callback <Функция>
• Возвращает: <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.log('Address in use, retrying...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});

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

• handle <Объект>
• backlog <число> Общий параметр функций server.listen()
• callback <Функция>
• Возвращает: <net.Server>

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

server.listen({
  host: 'localhost',
  port: 80,
  exclusive: true
});

Запуск сервера 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();

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

• <целое число>

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

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

server.ref()

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

Противоположность unref(), вызов ref() на ранее unref сервере не позволит программе завершиться, если это единственный оставшийся сервер (по умолчанию). Если сервер 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 <Объект> Доступные опции:
  • fd <число> Если указано, используется существующий сокет с заданным дескриптором файла; в противном случае создаётся новый сокет.
  • allowHalfOpen <логическое> Если установлено в false, сокет автоматически завершит запись при завершении чтения. См. net.createServer() и событие 'end' для подробностей. По умолчанию: false.
  • readable <логическое> Разрешить чтение из сокета, если передан fd, в противном случае игнорируется. По умолчанию: false.
  • writable <логическое> Разрешить запись в сокет, если передан fd, в противном случае игнорируется. По умолчанию: false.
  • signal <AbortSignal> Сигнал прерывания, который может быть использован для уничтожения сокета.
• Возвращает: <net.Socket>

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

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

Событие: 'close'

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

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

Событие: 'connect'

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

Событие: 'data'

• <Буфер> | <строка>

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

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

Событие: 'drain'

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

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

Событие: 'end'

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

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

Событие: 'error'

• <Ошибка>

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

Событие: 'lookup'

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

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

Событие: 'ready'

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

Вызывается сразу после 'connect'.

Событие: 'timeout'

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

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

socket.address()

• Возвращает: <Объект>

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

socket.bufferSize

• <целое>

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

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

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

socket.bytesRead

• <целое>

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

socket.bytesWritten

• <целое>

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

socket.connect()

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

Возможные варианты:

• socket.connect(options[, connectListener])
• socket.connect(path[, connectListener]) для подключений IPC.
• socket.connect(port[, host][, connectListener]) для TCP-соединений.
• Возвращает: <net.Socket> Сам сокет.

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

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

socket.connect(options[, connectListener])

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

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

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

• port <number> Обязательно. Порт, к которому должен подключиться сокет.
• host <string> Хост, к которому должен подключиться сокет. **По умолчанию:** 'localhost'.
• localAddress <string> Локальный адрес, с которого должен подключиться сокет.
• localPort <number> Локальный порт, с которого должен подключиться сокет.
• family <number>: Версия стека IP. Должно быть 4, 6, или 0. Значение 0 указывает, что разрешены как IPv4, так и IPv6 адреса. **По умолчанию:** 0.
• hints <number> Дополнительные dns.lookup() подсказки.
• lookup <Function> Пользовательская функция поиска. **По умолчанию:** dns.lookup().

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

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

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

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

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

const net = require('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])

• 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.end([data[, encoding]][, callback])

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

Закрывает сокет наполовину. Т.е., отправляет пакет FIN. Возможна дальнейшая отправка данных сервером.

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

socket.localAddress

• <строка>

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

socket.localPort

• <целое число>

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

socket.pause()

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

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

socket.pending

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

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

socket.ref()

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

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

socket.remoteAddress

• <строка>

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

socket.remoteFamily

• <строка>

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

socket.remotePort

• <целое число>

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

socket.resume()

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

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

socket.setEncoding([encoding])

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

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

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

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

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

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

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

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

socket.setNoDelay([noDelay])

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

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

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

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

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

socket.setTimeout(timeout[, callback])

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

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

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

socket.setTimeout(3000);
socket.on('timeout', () => {
  console.log('socket timeout');
  socket.end();
});

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

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

socket.timeout

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

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

socket.unref()

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

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

При установлении соединения на возвращенном сокете будет выпущен событие '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():

const net = require('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' });

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.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.createServer([options][, connectionListener])

• options <Объект>
  • allowHalfOpen <логическое значение> Если установлено в false, то сокет автоматически завершит сторону записи, когда сторона чтения завершится. По умолчанию: false.
  • pauseOnConnect <логическое значение> Указывает, следует ли приостановить сокет при входящих подключениях. По умолчанию: false.
• connectionListener <Функция> Автоматически устанавливается в качестве обработчика события 'connection'.
• Возвращает: <net.Сервер>

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

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

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

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

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

const net = require('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

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

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

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

$ nc -U /tmp/echo.sock

net.isIP(input)

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

Проверяет, является ли входной параметр IP-адресом. Возвращает 0 для недопустимых строк, возвращает 4 для IP-адресов версии 4 и возвращает 6 для IP-адресов версии 6.

net.isIPv4(input)

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

Возвращает true если входной параметр является IP-адресом версии 4, иначе возвращает false.

net.isIPv6(input)

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

Возвращает true если входной параметр является IP-адресом версии 6, иначе возвращает false.