Событие: 'close'

Событие 'close' возникает после закрытия сокета с помощью close(). После его возникновения на этом сокете больше не будут возникать новые события 'message'.

Событие: 'connect'

Событие 'connect' возникает после связывания сокета с удалённым адресом в результате успешного вызова connect().

Событие: 'error'

• exception <Error>

Событие 'error' возникает при любой ошибке. Функции обработчика события передаётся один объект Error.

Событие: 'listening'

Событие 'listening' возникает, когда dgram.Socket становится доступным по адресу и может принимать данные. Это происходит либо явно при вызове socket.bind(), либо неявно при первой отправке данных с помощью socket.send(). Пока dgram.Socket не прослушивает соединения, системные ресурсы не выделены, поэтому вызовы таких методов, как socket.address() и socket.setTTL(), завершатся ошибкой.

Событие: 'message'

Событие 'message' возникает, когда на сокете становится доступна новая дейтаграмма. Функции обработчика события передаются два аргумента: msg и rinfo.

• msg <Buffer> Сообщение.
• rinfo <Object> Информация об удалённом адресе.
  • address <string> Адрес отправителя.
  • family <string> Семейство адресов ('IPv4' или 'IPv6').
  • port <number> Порт отправителя.
  • size <number> Размер сообщения.

Если исходный адрес входящего пакета является локальным IPv6-адресом канала, к address добавляется имя интерфейса. Например, в поле адреса пакета, полученного через интерфейс en0, может быть указано значение 'fe80::2618:1234:ab11:3b9c%en0', где '%en0' — имя интерфейса в качестве суффикса идентификатора зоны.

socket.addMembership(multicastAddress[, multicastInterface])

• multicastAddress <string>
• multicastInterface <string>

Указывает ядру присоединиться к группе многоадресной рассылки по заданным multicastAddress и multicastInterface, используя параметр сокета IP_ADD_MEMBERSHIP. Если аргумент multicastInterface не указан, операционная система выберет интерфейс и добавит его в группу. Чтобы добавить в группу все доступные интерфейсы, вызовите addMembership несколько раз — по одному разу для каждого интерфейса.

При вызове для несвязанного сокета этот метод неявно выполняет привязку к случайному порту и прослушивает все интерфейсы.

При использовании одного UDP-сокета несколькими рабочими процессами cluster функцию socket.addMembership() необходимо вызвать только один раз, иначе возникнет ошибка EADDRINUSE:

import cluster from 'node:cluster';
import dgram from 'node:dgram';

if (cluster.isPrimary) {
  cluster.fork(); // Works ok.
  cluster.fork(); // Fails with EADDRINUSE.
} else {
  const s = dgram.createSocket('udp4');
  s.bind(1234, () => {
    s.addMembership('224.0.0.114');
  });
}

const cluster = require('node:cluster');
const dgram = require('node:dgram');

if (cluster.isPrimary) {
  cluster.fork(); // Works ok.
  cluster.fork(); // Fails with EADDRINUSE.
} else {
  const s = dgram.createSocket('udp4');
  s.bind(1234, () => {
    s.addMembership('224.0.0.114');
  });
}

socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])

• sourceAddress <string>
• groupAddress <string>
• multicastInterface <string>

Указывает ядру присоединиться к каналу многоадресной рассылки с определённым источником по заданным sourceAddress и groupAddress, используя multicastInterface с параметром сокета IP_ADD_SOURCE_MEMBERSHIP. Если аргумент multicastInterface не указан, операционная система выберет интерфейс и добавит его в группу. Чтобы добавить в группу все доступные интерфейсы, вызовите socket.addSourceSpecificMembership() несколько раз — по одному разу для каждого интерфейса.

При вызове для несвязанного сокета этот метод неявно выполняет привязку к случайному порту и прослушивает все интерфейсы.

socket.address()

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

Возвращает объект с информацией об адресе сокета. Для UDP-сокетов этот объект содержит свойства address, family и port.

При вызове для несвязанного сокета этот метод вызывает исключение EBADF.

socket.bind([port][, address][, callback])

• port <integer>
• address <string>
• callback <Function> Без параметров. Вызывается после завершения привязки.

Для UDP-сокетов заставляет dgram.Socket прослушивать дейтаграммы на заданном port и необязательном address. Если port не указан или равен 0, операционная система попытается привязать сокет к случайному порту. Если address не указан, операционная система попытается прослушивать все адреса. После завершения привязки возникает событие 'listening' и вызывается необязательная функция callback.

Одновременная регистрация обработчика события 'listening' и передача callback методу socket.bind() не повредит, но и не принесёт особой пользы.

Привязанный дейтаграммный сокет не позволяет процессу Node.js завершиться, пока он принимает дейтаграммы.

Если привязка завершается ошибкой, генерируется событие 'error'. В редких случаях (например, при попытке привязать закрытый сокет) может быть выброшено исключение Error.

Пример UDP-сервера, прослушивающего порт 41234:

import dgram from 'node:dgram';

const server = dgram.createSocket('udp4');

server.on('error', (err) => {
  console.error(`server error:\n${err.stack}`);
  server.close();
});

server.on('message', (msg, rinfo) => {
  console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`);
});

server.on('listening', () => {
  const address = server.address();
  console.log(`server listening ${address.address}:${address.port}`);
});

server.bind(41234);
// Prints: server listening 0.0.0.0:41234

const dgram = require('node:dgram');
const server = dgram.createSocket('udp4');

server.on('error', (err) => {
  console.error(`server error:\n${err.stack}`);
  server.close();
});

server.on('message', (msg, rinfo) => {
  console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`);
});

server.on('listening', () => {
  const address = server.address();
  console.log(`server listening ${address.address}:${address.port}`);
});

server.bind(41234);
// Prints: server listening 0.0.0.0:41234

socket.bind(options[, callback])

• options <Object> Обязательный параметр. Поддерживает следующие свойства:
  • port <integer>
  • address <string>
  • exclusive <boolean>
  • fd <integer>
• callback <Function>

Для UDP-сокетов заставляет dgram.Socket прослушивать дейтаграммы на заданном port и необязательном address, переданных в качестве свойств объекта options, который является первым аргументом. Если port не указан или равен 0, операционная система попытается привязать сокет к случайному порту. Если address не указан, операционная система попытается прослушивать все адреса. После завершения привязки возникает событие 'listening' и вызывается необязательная функция callback.

Объект options может содержать свойство fd. Если задано значение fd больше 0, метод использует существующий сокет с указанным файловым дескриптором. В этом случае свойства port и address игнорируются.

Одновременная регистрация обработчика события 'listening' и передача callback методу socket.bind() не повредит, но и не принесёт особой пользы.

Объект options может содержать дополнительное свойство exclusive, которое используется при работе с объектами dgram.Socket совместно с модулем cluster. Если для exclusive установлено значение false (по умолчанию), рабочие процессы кластера используют один и тот же базовый дескриптор сокета, что позволяет распределять обработку соединений. Если же exclusive равно true, дескриптор не используется совместно, и попытка совместного использования порта приводит к ошибке. Создание dgram.Socket с параметром reusePort, установленным в true, приводит к тому, что при вызове socket.bind() значение exclusive всегда равно true.

Привязанный дейтаграммный сокет не позволяет процессу Node.js завершиться, пока он принимает дейтаграммы.

Если привязка завершается ошибкой, генерируется событие 'error'. В редких случаях (например, при попытке привязать закрытый сокет) может быть выброшено исключение Error.

Ниже приведён пример сокета, прослушивающего эксклюзивный порт.

socket.bind({
  address: 'localhost',
  port: 8000,
  exclusive: true,
}); copy

socket.close([callback])

• callback <Function> Вызывается после закрытия сокета.

Закрывает базовый сокет и прекращает прослушивание данных на нём. Если указана функция обратного вызова, она добавляется в качестве обработчика события 'close'.

socket[Symbol.asyncDispose]()

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

socket.connect(port[, address][, callback])

• port <integer>
• address <string>
• callback <Function> Вызывается после установления соединения или при ошибке.

Связывает dgram.Socket с удалённым адресом и портом. Все сообщения, отправляемые этим дескриптором, автоматически направляются указанному адресату. Кроме того, сокет будет принимать сообщения только от этого удалённого узла. Попытка вызвать connect() для уже подключённого сокета приведёт к исключению ERR_SOCKET_DGRAM_IS_CONNECTED. Если address не задан, по умолчанию используется '127.0.0.1' (для сокетов udp4) или '::1' (для сокетов udp6). После установления соединения возникает событие 'connect' и вызывается необязательная функция callback. В случае сбоя вызывается callback, а если она отсутствует, возникает событие 'error'.

socket.disconnect()

Синхронная функция, отменяющая привязку подключённого dgram.Socket к удалённому адресу. Попытка вызвать disconnect() для несвязанного или уже отключённого сокета приведёт к исключению ERR_SOCKET_DGRAM_NOT_CONNECTED.

socket.dropMembership(multicastAddress[, multicastInterface])

• multicastAddress <string>
• multicastInterface <string>

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

Если multicastInterface не указан, операционная система попытается удалить членство для всех допустимых интерфейсов.

socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])

• sourceAddress <string>
• groupAddress <string>
• multicastInterface <string>

Указывает ядру покинуть канал многоадресной рассылки с определённым источником по заданным sourceAddress и groupAddress, используя параметр сокета IP_DROP_SOURCE_MEMBERSHIP. Этот метод автоматически вызывается ядром при закрытии сокета или завершении процесса, поэтому большинству приложений он не понадобится.

Если multicastInterface не указан, операционная система попытается удалить членство для всех допустимых интерфейсов.

socket.getRecvBufferSize()

• Возвращает: <number> размер буфера приёма сокета SO_RCVBUF в байтах.

При вызове для несвязанного сокета этот метод вызывает исключение ERR_SOCKET_BUFFER_SIZE.

socket.getSendBufferSize()

• Возвращает: <number> размер буфера отправки сокета SO_SNDBUF в байтах.

При вызове для несвязанного сокета этот метод вызывает исключение ERR_SOCKET_BUFFER_SIZE.

socket.getSendQueueSize()

• Возвращает: <number> количество байтов, поставленных в очередь на отправку.

socket.getSendQueueCount()

• Возвращает: <number> количество запросов на отправку, которые находятся в очереди и ожидают обработки.

socket.ref()

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

По умолчанию привязка сокета не позволяет процессу Node.js завершиться, пока сокет открыт. Метод socket.unref() позволяет исключить сокет из подсчёта ссылок, поддерживающего активность процесса Node.js. Метод socket.ref() снова добавляет сокет в подсчёт ссылок и восстанавливает поведение по умолчанию.

Повторный вызов socket.ref() не приводит к дополнительным эффектам.

Метод socket.ref() возвращает ссылку на сокет, поэтому вызовы можно объединять в цепочку.

socket.remoteAddress()

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

Возвращает объект, содержащий address, family и port удалённой конечной точки. Если сокет не подключён, этот метод вызывает исключение ERR_SOCKET_DGRAM_NOT_CONNECTED.

socket.send(msg[, offset, length][, port][, address][, callback])

• msg <Buffer> | <TypedArray> | <DataView> | <string> | <Array> Отправляемое сообщение.
• offset <integer> Смещение в буфере, с которого начинается сообщение.
• length <integer> Количество байтов в сообщении.
• port <integer> Порт назначения.
• address <string> Имя хоста или IP-адрес назначения.
• callback <Function> Вызывается после отправки сообщения.

Отправляет дейтаграмму через сокет. Для сокетов без подключения необходимо указать port и address назначения. Подключённые сокеты используют связанную с ними удалённую конечную точку, поэтому аргументы port и address указывать нельзя.

Аргумент msg содержит отправляемое сообщение. В зависимости от его типа поведение может различаться. Если msg — это Buffer, любой TypedArray или DataView, параметры offset и length задают соответственно смещение в Buffer, с которого начинается сообщение, и количество байтов в сообщении. Если msg — это String, он автоматически преобразуется в Buffer с кодировкой 'utf8'. Для сообщений, содержащих многобайтовые символы, offset и length вычисляются с учётом длины в байтах, а не позиции символа. Если msg — это массив, параметры offset и length указывать нельзя.

Аргумент address является строкой. Если значение address — это имя хоста, для определения его адреса используется DNS. Если address не задан или имеет значение null, по умолчанию используется '127.0.0.1' (для сокетов udp4) или '::1' (для сокетов udp6).

Если сокет ранее не был привязан вызовом bind, ему назначается случайный номер порта и он привязывается к адресу «все интерфейсы» ('0.0.0.0' для сокетов udp4, '::0' для сокетов udp6).

Необязательную функцию callback можно указать для обработки ошибок DNS или определения момента, когда объект buf можно безопасно использовать повторно. Поиск DNS откладывает отправку как минимум на один такт цикла событий Node.js.

Единственный способ достоверно узнать, что дейтаграмма отправлена, — использовать callback. Если возникает ошибка и задан callback, ошибка передаётся первым аргументом функции callback. Если callback не задан, ошибка генерируется как событие 'error' объекта socket.

Параметры смещения и длины необязательны, но если используется один из них, необходимо задать оба. Они поддерживаются только в том случае, если первым аргументом является Buffer, TypedArray или DataView.

При вызове для несвязанного сокета этот метод вызывает исключение ERR_SOCKET_BAD_PORT.

Пример отправки UDP-пакета на порт хоста localhost;

import dgram from 'node:dgram';
import { Buffer } from 'node:buffer';

const message = Buffer.from('Some bytes');
const client = dgram.createSocket('udp4');
client.send(message, 41234, 'localhost', (err) => {
  client.close();
});

const dgram = require('node:dgram');
const { Buffer } = require('node:buffer');

const message = Buffer.from('Some bytes');
const client = dgram.createSocket('udp4');
client.send(message, 41234, 'localhost', (err) => {
  client.close();
});

Пример отправки UDP-пакета, составленного из нескольких буферов, на порт хоста 127.0.0.1;

import dgram from 'node:dgram';
import { Buffer } from 'node:buffer';

const buf1 = Buffer.from('Some ');
const buf2 = Buffer.from('bytes');
const client = dgram.createSocket('udp4');
client.send([buf1, buf2], 41234, (err) => {
  client.close();
});

const dgram = require('node:dgram');
const { Buffer } = require('node:buffer');

const buf1 = Buffer.from('Some ');
const buf2 = Buffer.from('bytes');
const client = dgram.createSocket('udp4');
client.send([buf1, buf2], 41234, (err) => {
  client.close();
});

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

Пример отправки UDP-пакета через сокет, подключённый к порту хоста localhost:

import dgram from 'node:dgram';
import { Buffer } from 'node:buffer';

const message = Buffer.from('Some bytes');
const client = dgram.createSocket('udp4');
client.connect(41234, 'localhost', (err) => {
  client.send(message, (err) => {
    client.close();
  });
});

const dgram = require('node:dgram');
const { Buffer } = require('node:buffer');

const message = Buffer.from('Some bytes');
const client = dgram.createSocket('udp4');
client.connect(41234, 'localhost', (err) => {
  client.send(message, (err) => {
    client.close();
  });
});

socket.setBroadcast(flag)

• flag <boolean>

Включает или отключает параметр сокета SO_BROADCAST. Если он включён (значение true), UDP-пакеты можно отправлять на широковещательный адрес локального интерфейса.

При вызове для несвязанного сокета этот метод вызывает исключение EBADF.

socket.setMulticastInterface(multicastInterface)

• multicastInterface <string>

Все упоминания области действия в этом разделе относятся к индексам зоны IPv6, которые определены в RFC 4007. В строковом представлении IP-адрес с индексом области действия записывается как 'IP%scope', где областью действия является имя или номер интерфейса.

Устанавливает для сокета исходящий интерфейс многоадресной рассылки по умолчанию: выбранный интерфейс или системный выбор интерфейса. multicastInterface должен быть допустимым строковым представлением IP-адреса семейства сокета.

Для сокетов IPv4 это должен быть IP-адрес, настроенный для нужного физического интерфейса. Все пакеты, отправляемые на адрес многоадресной рассылки через сокет, будут отправляться через интерфейс, определённый при последнем успешном вызове этого метода.

Для сокетов IPv6 multicastInterface должен включать область действия, указывающую интерфейс, как показано в следующих примерах. В IPv6 отдельные вызовы send также могут использовать явную область действия в адресах, поэтому последний успешный вызов этого метода влияет только на пакеты, отправленные на адрес многоадресной рассылки без указания явной области действия.

Этот метод выбрасывает EBADF при вызове для несвязанного сокета.

const socket = dgram.createSocket('udp6');

socket.bind(1234, () => {
  socket.setMulticastInterface('::%eth1');
}); copy

const socket = dgram.createSocket('udp6');

socket.bind(1234, () => {
  socket.setMulticastInterface('::%2');
}); copy

const socket = dgram.createSocket('udp4');

socket.bind(1234, () => {
  socket.setMulticastInterface('10.0.0.2');
}); copy

socket.setMulticastLoopback(flag)

• flag <boolean>

Включает или отключает параметр сокета IP_MULTICAST_LOOP. Если установлено значение true, пакеты многоадресной рассылки также будут приниматься на локальном интерфейсе.

Этот метод выбрасывает EBADF при вызове для несвязанного сокета.

socket.setMulticastTTL(ttl)

• ttl <integer>

Устанавливает параметр сокета IP_MULTICAST_TTL. Хотя TTL обычно означает «время жизни» (Time to Live), в данном контексте он указывает количество переходов между IP-узлами, которое может пройти пакет, а именно для трафика многоадресной рассылки. Каждый маршрутизатор или шлюз, пересылающий пакет, уменьшает значение TTL. Если маршрутизатор уменьшает TTL до 0, пакет не будет переслан.

Аргумент ttl может принимать значения от 0 до 255. Значение по умолчанию в большинстве систем — 1.

Этот метод выбрасывает EBADF при вызове для несвязанного сокета.

socket.setRecvBufferSize(size)

• size <integer>

Устанавливает параметр сокета SO_RCVBUF. Задаёт максимальный размер буфера приёма сокета в байтах.

Этот метод выбрасывает ERR_SOCKET_BUFFER_SIZE при вызове для несвязанного сокета.

socket.setSendBufferSize(size)

• size <integer>

Устанавливает параметр сокета SO_SNDBUF. Задаёт максимальный размер буфера отправки сокета в байтах.

Этот метод выбрасывает ERR_SOCKET_BUFFER_SIZE при вызове для несвязанного сокета.

socket.setTTL(ttl)

• ttl <integer>

Устанавливает параметр сокета IP_TTL. Хотя TTL обычно означает «время жизни» (Time to Live), в данном контексте он указывает количество переходов между IP-узлами, которое может пройти пакет. Каждый маршрутизатор или шлюз, пересылающий пакет, уменьшает значение TTL. Если маршрутизатор уменьшает TTL до 0, пакет не будет переслан. Изменение значения TTL обычно выполняется для сетевых проб или при многоадресной рассылке.

Аргумент ttl может принимать значения от 1 до 255. Значение по умолчанию в большинстве систем — 64.

Этот метод выбрасывает EBADF при вызове для несвязанного сокета.

socket.unref()

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

По умолчанию привязка сокета не позволяет процессу Node.js завершиться, пока сокет открыт. Метод socket.unref() позволяет исключить сокет из подсчёта ссылок, поддерживающего активность процесса Node.js, благодаря чему процесс может завершиться, даже если сокет всё ещё ожидает подключения.

Повторные вызовы socket.unref() не дадут дополнительного эффекта.

Метод socket.unref() возвращает ссылку на сокет, поэтому вызовы можно объединять в цепочку.

dgram.createSocket(options[, callback])

• options <Object> Доступны следующие параметры:
  • type <string> Семейство сокета. Должно быть равно 'udp4' или 'udp6'. Обязательный параметр.
  • reuseAddr <boolean> Если задано значение true, socket.bind() повторно использует адрес, даже если другой процесс уже привязал к нему сокет; однако получать данные сможет только один сокет. По умолчанию: false.
  • reusePort <boolean> Если задано значение true, socket.bind() повторно использует порт, даже если другой процесс уже привязал к нему сокет. Входящие дейтаграммы распределяются между прослушивающими сокетами. Параметр доступен только на некоторых платформах, таких как Linux 3.9+, DragonFlyBSD 3.6+, FreeBSD 12.0+, Solaris 11.4 и AIX 7.2.5+. На неподдерживаемых платформах этот параметр вызывает ошибку при привязке сокета. По умолчанию: false.
  • ipv6Only <boolean> Установка ipv6Only в значение true отключит поддержку двойного стека, то есть привязка к адресу :: не приведёт к привязке 0.0.0.0. По умолчанию: false.
  • recvBufferSize <number> Устанавливает значение сокета SO_RCVBUF.
  • sendBufferSize <number> Устанавливает значение сокета SO_SNDBUF.
  • lookup <Function> Пользовательская функция поиска. По умолчанию: dns.lookup().
  • signal <AbortSignal> AbortSignal, который можно использовать для закрытия сокета.
  • receiveBlockList <net.BlockList> receiveBlockList можно использовать для отбрасывания входящих дейтаграмм с определённых IP-адресов, из диапазонов IP-адресов или подсетей. Это не работает, если сервер находится за обратным прокси-сервером, NAT и т. п., поскольку проверяемый адрес будет адресом прокси-сервера или адресом, указанным NAT.
  • sendBlockList <net.BlockList> sendBlockList можно использовать для отключения исходящего доступа к определённым IP-адресам, диапазонам IP-адресов или подсетям.
• callback <Function> Назначается обработчиком событий 'message'. Необязательный параметр.
• Возвращает: <dgram.Socket>

Создаёт объект dgram.Socket. После создания сокета вызов socket.bind() укажет сокету начать прослушивание сообщений дейтаграмм. Если параметры address и port не переданы в socket.bind(), метод привяжет сокет к адресу «все интерфейсы» на случайном порту (корректно обрабатывая сокеты udp4 и udp6). Привязанный адрес и порт можно получить с помощью socket.address().address и socket.address().port.

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

const controller = new AbortController();
const { signal } = controller;
const server = dgram.createSocket({ type: 'udp4', signal });
server.on('message', (msg, rinfo) => {
  console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`);
});
// Later, when you want to close the server.
controller.abort(); copy

dgram.createSocket(type[, callback])

• type <string> Либо 'udp4', либо 'udp6'.
• callback <Function> Назначается обработчиком событий 'message'.
• Возвращает: <dgram.Socket>

Создаёт объект dgram.Socket указанного типа type.

После создания сокета вызов socket.bind() укажет сокету начать прослушивание сообщений дейтаграмм. Если параметры address и port не переданы в socket.bind(), метод привяжет сокет к адресу «все интерфейсы» на случайном порту (корректно обрабатывая сокеты udp4 и udp6). Привязанный адрес и порт можно получить с помощью socket.address().address и socket.address().port.