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

Указывает ядру присоединиться к группе multicast по заданным 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>

Указывает ядру присоединиться к multicast-каналу с фильтрацией по источнику по заданным 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>

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

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

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

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

Указывает ядру покинуть multicast-канал с фильтрацией по источнику по заданным 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 не задан или имеет значение nullish, по умолчанию используется '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-адресов или подсетей IP. Это не работает, если сервер находится за обратным прокси-сервером, NAT и т. п., поскольку проверяемый адрес будет адресом прокси-сервера или адресом, указанным NAT.
  • sendBlockList <net.BlockList> sendBlockList можно использовать для отключения исходящего доступа к определённым IP-адресам, диапазонам 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.