Класс: dgram.Socket

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

Капсулирует функциональность дейтаграмм.

Новые экземпляры dgram.Socket создаются с помощью dgram.createSocket(). Ключевое слово new не должно использоваться для создания экземпляров dgram.Socket.

Событие: 'close'

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

Событие: 'connect'

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

Событие: 'error'

• exception <Ошибка>

Событие 'error' генерируется всякий раз, когда возникает ошибка. Обработчик события получает один аргумент — объект Error.

Событие: 'listening'

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

Событие: 'message'

Событие 'message' генерируется при получении нового дейтаграммы на сокете. Обработчик события получает два аргумента: msg и rinfo.

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

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

socket.addMembership(multicastAddress[, multicastInterface])

• multicastAddress <строка>
• multicastInterface <строка>

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

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

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

const cluster = require('cluster');
const dgram = require('dgram');
if (cluster.isMaster) {
  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 <строка>
• groupAddress <строка>
• multicastInterface <строка>

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

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

socket.address()

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

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

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

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

• port <целое>
• address <строка>
• callback <Функция> без параметров. Вызывается при завершении привязки.

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

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

Связанный сокет дейтаграмм удерживает процесс Node.js для получения сообщений дейтаграмм.

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

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

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

server.on('error', (err) => {
  console.log(`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 <Объект> Обязательно. Поддерживает следующие свойства:
  • port <целое>
  • address <строка>
  • exclusive <логическое>
  • fd <целое>
• callback <Функция>

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

Связанный сокет дейтаграмм поддерживает процесс Node.js, ожидая сообщений дейтаграмм.

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

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

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

socket.close([callback])

• callback <Функция> Вызывается, когда сокет был закрыт.

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

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

• port <целое число>
• address <строка>
• callback <Функция> Вызывается при успешном подключении или возникновении ошибки.

Устанавливает связь сокета 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 <строка>
• multicastInterface <строка>

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

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

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

• sourceAddress <строка>
• groupAddress <строка>
• multicastInterface <строка>

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

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

socket.getRecvBufferSize()

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

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

socket.getSendBufferSize()

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

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

socket.ref()

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

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

Вызов socket.ref() несколько раз не окажет дополнительного влияния.

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

socket.remoteAddress()

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

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

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

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

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

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

Аргумент address представляет собой строку. Если значение address является именем хоста, для разрешения адреса хоста будет использоваться DNS. Если address не указано или имеет ложное значение, по умолчанию будет использоваться '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;

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

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

const dgram = require('dgram');
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:

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

Примечание о размере UDP-датаграммы

Максимальный размер IPv4/v6 датаграммы зависит от MTU (максимального размера передачи) и размера поля Payload Length.

• Поле Payload Length имеет ширину 16 бит, что означает, что обычная полезная нагрузка не может превышать 64 Кбайт, включая заголовок интернета и данные (65 507 байт = 65 535 − 8 байт заголовка UDP − 20 байт заголовка IP); это обычно верно для интерфейсов обратной связи, но такие длинные датаграммы непрактичны для большинства хостов и сетей.

• MTU — это максимальный размер, который может поддерживать конкретная технология канального уровня для датаграмм. Для любого канала IPv4 требует минимального MTU в 68 октетах, в то время как рекомендуемый MTU для IPv4 составляет 576 (обычно рекомендуется как MTU для приложений типа модемов), независимо от того, поступают ли они целиком или фрагментами.

  Для IPv6 минимальный MTU составляет 1280 октетов. Однако обязательный минимальный размер буфера для сборки фрагментов составляет 1500 октетов. Значение 68 октетов очень мало, так как большинство современных технологий канального уровня, таких как Ethernet, имеют минимальный MTU в 1500.

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

socket.setBroadcast(flag)

• flag <логическое>

Устанавливает или сбрасывает опцию сокета SO_BROADCAST. Когда установлено в true, UDP-пакеты могут быть отправлены на адрес широковещательной рассылки локального интерфейса.

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

socket.setMulticastInterface(multicastInterface)

• multicastInterface <строка>

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

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

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

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

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

Пример: исходящий мультиадресный интерфейс IPv6

На большинстве систем, где формат области использует имя интерфейса:

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

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

В Windows, где формат области использует номер интерфейса:

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

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

Пример: исходящий мультиадресный интерфейс IPv4

Все системы используют IP-адрес хоста на желаемом физическом интерфейсе:

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

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

Результаты вызова

Вызов на сокете, который не готов к отправке или больше не открыт, может привести к ошибке Не запущено Error.

Если multicastInterface не может быть обработана как IP-адрес, выбрасывается EINVAL System Error.

В IPv4, если multicastInterface является допустимым адресом, но не соответствует ни одному интерфейсу, или если адрес не соответствует семейству, выбрасывается System Error , например, EADDRNOTAVAIL или EPROTONOSUP.

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

Можно использовать адрес семейства адресов сокета ANY (IPv4 '0.0.0.0' или IPv6 '::') для возврата управления по умолчанию для исходящего интерфейса сокета системе для будущих мультиадресных пакетов.

socket.setMulticastLoopback(flag)

• flag <логическое>

Устанавливает или сбрасывает опцию сокета IP_MULTICAST_LOOP. При установке в true мультиадресные пакеты также будут приниматься на локальном интерфейсе.

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

socket.setMulticastTTL(ttl)

• ttl <целое>

Устанавливает опцию сокета IP_MULTICAST_TTL. Хотя TTL обычно обозначает "время жизни", в данном контексте он определяет количество IP-ходов, которые пакету разрешено пройти, особенно для мультиадресного трафика. Каждый маршрутизатор или шлюз, который пересылает пакет, декрементирует TTL. Если TTL декрементируется до 0 маршрутизатором, он не будет пересылаться.

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

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

socket.setRecvBufferSize(size)

• size <целое>

Устанавливает опцию сокета SO_RCVBUF. Устанавливает максимальный буфер приема сокета в байтах.

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

socket.setSendBufferSize(size)

• size <целое>

Устанавливает опцию сокета SO_SNDBUF. Устанавливает максимальный буфер отправки сокета в байтах.

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

socket.setTTL(ttl)

• ttl <целое>

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

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

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

socket.unref()

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

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

Вызов socket.unref() несколько раз не приведёт к дополнительным эффектам.

Метод socket.unref() возвращает ссылку на сокет, позволяя цепочку вызовов.

dgram функции модуля

dgram.createSocket(options[, callback])

• options <Объект> Доступные опции:
  • type <строка> Семейство сокета. Должно быть либо 'udp4' или 'udp6' . Обязательно.
  • reuseAddr <булево> При значении true метод socket.bind() будет повторно использовать адрес, даже если другой процесс уже привязал сокет к нему. По умолчанию: false.
  • ipv6Only <булево> Установка ipv6Only в true отключит поддержку двойной стековой адресации, т.е. привязка к адресу :: не приведет к привязке 0.0.0.0 . По умолчанию: false.
  • recvBufferSize <число> Устанавливает значение сокета SO_RCVBUF.
  • sendBufferSize <число> Устанавливает значение сокета SO_SNDBUF.
  • lookup <Функция> Пользовательская функция поиска. По умолчанию: dns.lookup().
  • signal <AbortSignal> Объект AbortSignal, который можно использовать для закрытия сокета.
• callback <Функция> Прикрепляется как обработчик событий 'message'. Необязательно.
• Возвращает: <dgram.Сокет>

Создаёт объект 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();

dgram.createSocket(type[, callback])

• type <строка> Либо 'udp4' или 'udp6'.
• callback <Функция> Прикрепляется как обработчик событий 'message'.
• Возвращает: <dgram.Сокет>

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

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