UDP / Сокеты дейтаграмм

Модуль dgram предоставляет реализацию сокетов UDP дейтаграмм.

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', () => {
  var address = server.address();
  console.log(`server listening ${address.address}:${address.port}`);
});

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

Класс: dgram.Socket

Объект dgram.Socket — это EventEmitter, который инкапсулирует функциональность дейтаграмм.

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

Событие: 'close'

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

Событие: 'error'

• exception <Ошибка>

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

Событие: 'listening'

Событие 'listening' генерируется всякий раз, когда сокет начинает прослушивать сообщения дейтаграмм. Это происходит сразу после создания сокетов UDP.

Событие: 'message'

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

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

socket.addMembership(multicastAddress[, multicastInterface])

• multicastAddress <Строка>
• multicastInterface <Строка>, Необязательно

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

socket.address()

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

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', () => {
  var address = server.address();
  console.log(`server listening ${address.address}:${address.port}`);
});

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

socket.bind(options[, callback])

• options <Объект> - Требуется. Поддерживает следующие свойства:
  • port <Число> - Необязательно.
  • address <Строка> - Необязательно.
  • exclusive <Булево> - Необязательно.
• callback <Функция> - Необязательно.

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

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

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

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

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

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

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

socket.close([callback])

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

socket.dropMembership(multicastAddress[, multicastInterface])

• multicastAddress <Строка>
• multicastInterface <Строка>, Необязательно

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

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

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

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

Отправляет дейтаграмму по сокету. Необходимо указать адрес назначения port и address.

Аргумент buf — это объект Buffer, содержащий сообщение. Аргументы offset и length указывают смещение в Buffer начала сообщения и количество байтов в сообщении соответственно. При сообщениях, содержащих многобайтовые символы, offset и length будут рассчитываться относительно длины в байтах, а не позиции символа.

Аргумент address — это строка. Если значение address является именем хоста, для получения адреса хоста используется DNS. Если address не указан или пустая строка, вместо него будут использованы '0.0.0.0' или '::0'. В зависимости от конфигурации сети эти значения по умолчанию могут не работать; поэтому лучше явно указывать адрес назначения.

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

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

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

Пример отправки UDP-пакета на случайный порт на localhost;

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

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

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

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

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

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

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

socket.setBroadcast(flag)

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

socket.setMulticastLoopback(flag)

• flag <Булево>

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

socket.setMulticastTTL(ttl)

• ttl <Число> Целое число

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

Аргумент, передаваемый в socket.setMulticastTTL() — это количество пересадок от 0 до 255. По умолчанию на большинстве систем 1, но может меняться.

socket.setTTL(ttl)

• ttl <Число> Целое число

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

Аргумент для socket.setTTL() — это количество пересадок от 1 до 255. По умолчанию на большинстве систем 64, но может меняться.

socket.ref()

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

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

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

socket.unref()

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

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

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

Изменение асинхронного socket.bind() поведения

Начиная с Node.js v0.10, dgram.Socket#bind() изменился на асинхронную модель выполнения. Код, наследующий синхронное поведение, как в следующем примере:

const s = dgram.createSocket('udp4');
s.bind(1234);
s.addMembership('224.0.0.114');

должен быть изменён на передачу функции обратного вызова в функцию dgram.Socket#bind():

const s = dgram.createSocket('udp4');
s.bind(1234, () => {
  s.addMembership('224.0.0.114');
});

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

dgram.createSocket(options[, callback])

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

Создает объект dgram.Socket Аргумент options — это объект, который должен содержать поле type типа udp4 или udp6 и необязательное булево поле reuseAddr.

Когда reuseAddr равно true, socket.bind() будет повторно использовать адрес, даже если другой процесс уже привязал сокет к нему. reuseAddr по умолчанию равно false. Необязательная функция callback добавляется как обработчик событий 'message'.

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

dgram.createSocket(type[, callback])

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

Создаёт объект dgram.Socket указанного типа type. Аргумент type может быть либо udp4, либо udp6. Можно передать необязательную функцию callback, которая будет добавлена в качестве обработчика событий 'message'.

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