UDP/датаграммные сокеты

[Стабильно: 2 - Стабильно]

Стабильно: 2 Стабильность: 2 - Стабильно

Исходный код: lib/dgram.js

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

ESMCJS

import dgram from 'node:dgram'

const server = dgram.createSocket('udp4')

server.on('error', err => {
  console.error(`ошибка сервера:\n${err.stack}`)
  server.close()
})

server.on('message', (msg, rinfo) => {
  console.log(`сервер получил: ${msg} от ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`сервер слушает ${address.address}:${address.port}`)
})

server.bind(41234)
// Выводит: server listening 0.0.0.0:41234

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

server.on('error', err => {
  console.error(`ошибка сервера:\n${err.stack}`)
  server.close()
})

server.on('message', (msg, rinfo) => {
  console.log(`сервер получил: ${msg} от ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`сервер слушает ${address.address}:${address.port}`)
})

server.bind(41234)
// Выводит: server listening 0.0.0.0:41234

Класс: `dgram.Socket`

Добавлено в: v0.1.99

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

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

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

Событие: `'close'`

Добавлено в: v0.1.99

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

Событие: `'connect'`

Добавлено в: v12.0.0

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

Событие: `'error'`

Добавлено в: v0.1.99

exception <Error>

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

Событие: `'listening'`

Добавлено в: v0.1.99

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

Событие: `'message'`

[История]

Версия	Изменения
v18.4.0	Свойство `family` теперь возвращает строку, а не число.
v18.0.0	Свойство `family` теперь возвращает число, а не строку.
v0.1.99	Добавлено в: v0.1.99

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

Добавлено в: v0.6.9

multicastAddress <string>
multicastInterface <string>

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

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

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

ESMCJS

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

if (cluster.isPrimary) {
  cluster.fork() // Работает нормально.
  cluster.fork() // Сбой с 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() // Работает нормально.
  cluster.fork() // Сбой с EADDRINUSE.
} else {
  const s = dgram.createSocket('udp4')
  s.bind(1234, () => {
    s.addMembership('224.0.0.114')
  })
}

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

Добавлено в: v13.1.0, v12.16.0

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

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

`socket.address()`

Добавлено в: v0.1.99

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

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

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

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

[История]

Версия	Изменения
v0.9.1	Метод был изменен на асинхронную модель выполнения. Старый код нужно будет изменить, чтобы передавать функцию обратного вызова методу.
v0.1.99	Добавлено в: v0.1.99

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:

ESMCJS

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)
// Выводит: 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)
// Выводит: server listening 0.0.0.0:41234

`socket.bind(options[, callback])`

Добавлено в: v0.11.14

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, приводит к тому, что exclusive всегда будет иметь значение true при вызове socket.bind().

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

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

Пример прослушивания сокетом на эксклюзивном порту показан ниже.

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

`socket.close([callback])`

Добавлено в: v0.1.99

callback <Function> Вызывается, когда сокет был закрыт.

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

`socket[Symbol.asyncDispose]()`

Добавлено в: v20.5.0, v18.18.0

[Стабильность: 1 - Экспериментальная]

Стабильность: 1 Стабильность: 1 - Экспериментальная

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

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

Добавлено в: v12.0.0

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()`

Добавлено в: v12.0.0

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

`socket.dropMembership(multicastAddress[, multicastInterface])`

Добавлено в: v0.6.9

multicastAddress <string>
multicastInterface <string>

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

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

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

Добавлено в: v13.1.0, v12.16.0

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

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

`socket.getRecvBufferSize()`

Добавлено в: v8.7.0

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

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

`socket.getSendBufferSize()`

Добавлено в: v8.7.0

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

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

`socket.getSendQueueSize()`

Добавлено в: v18.8.0, v16.19.0

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

`socket.getSendQueueCount()`

Добавлено в: v18.8.0, v16.19.0

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

`socket.ref()`

Добавлено в: v0.9.1

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

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

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

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

`socket.remoteAddress()`

Добавлено в: v12.0.0

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

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

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

[История]

Версия	Изменения
v17.0.0	Параметр `address` теперь принимает только `string`, `null` или `undefined`.
v14.5.0, v12.19.0	Параметр `msg` теперь может быть любым `TypedArray` или `DataView`.
v12.0.0	Добавлена поддержка отправки данных на подключенные сокеты.
v8.0.0	Параметр `msg` теперь может быть `Uint8Array`.
v8.0.0	Параметр `address` теперь всегда необязателен.
v6.0.0	При успешном выполнении, `callback` теперь будет вызываться с аргументом `error`, равным `null`, а не `0`.
v5.7.0	Параметр `msg` теперь может быть массивом. Также, параметры `offset` и `length` теперь необязательны.
v0.1.99	Добавлено в: v0.1.99

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;

ESMCJS

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;

ESMCJS

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:

ESMCJS

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()
  })
})

Заметка о размере датаграммы UDP

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

Поле Payload Length имеет ширину 16 бит, что означает, что обычная полезная нагрузка не может превышать 64K октетов, включая интернет-заголовок и данные (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)`

Добавлено в: v0.6.9

flag <boolean>

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

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

`socket.setMulticastInterface(multicastInterface)`

Добавлено в: v8.6.0

multicastInterface <string>

Все ссылки на область действия в этом разделе относятся к Индексам зон IPv6, которые определены RFC 4007. В строковом виде IP с индексом области действия записывается как 'IP%scope', где 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')
})

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

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

Если multicastInterface не удается преобразовать в IP-адрес, возникает ошибка EINVAL System Error.

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

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

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

`socket.setMulticastLoopback(flag)`

Добавлено в: v0.3.8

flag <boolean>

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

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

`socket.setMulticastTTL(ttl)`

Добавлено в: v0.3.8

ttl <integer>

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

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

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

`socket.setRecvBufferSize(size)`

Добавлено в: v8.7.0

size <integer>

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

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

`socket.setSendBufferSize(size)`

Добавлено в: v8.7.0

size <integer>

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

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

`socket.setTTL(ttl)`

Добавлено в: v0.1.101

ttl <integer>

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

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

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

`socket.unref()`

Добавлено в: v0.9.1

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

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

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

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

Функции модуля `node:dgram`

`dgram.createSocket(options[, callback])`

[История]

Версия	Изменения
v23.1.0	Поддерживается опция `reusePort`.
v15.8.0	Добавлена поддержка AbortSignal.
v11.4.0	Поддерживается опция `ipv6Only`.
v8.7.0	Теперь поддерживаются опции `recvBufferSize` и `sendBufferSize`.
v8.6.0	Поддерживается опция `lookup`.
v0.11.13	Добавлено в: v0.11.13

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}`)
})
// Позже, когда вы захотите закрыть сервер.
controller.abort()

`dgram.createSocket(type[, callback])`

Добавлено в версии: v0.1.99

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.

UDP/датаграммные сокеты ​

Класс: dgram.Socket ​

Событие: 'close' ​

Событие: 'connect' ​

Событие: 'error' ​

Событие: 'listening' ​

Событие: 'message' ​

socket.addMembership(multicastAddress[, multicastInterface]) ​

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

socket.address() ​

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

socket.bind(options[, callback]) ​

socket.close([callback]) ​

socket[Symbol.asyncDispose]() ​

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

socket.disconnect() ​

socket.dropMembership(multicastAddress[, multicastInterface]) ​

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

socket.getRecvBufferSize() ​

socket.getSendBufferSize() ​

socket.getSendQueueSize() ​

socket.getSendQueueCount() ​

socket.ref() ​

socket.remoteAddress() ​

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

Заметка о размере датаграммы UDP ​

socket.setBroadcast(flag) ​

socket.setMulticastInterface(multicastInterface) ​

Пример: исходящий многоадресный интерфейс IPv6 ​

Пример: исходящий многоадресный интерфейс IPv4 ​

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

socket.setMulticastLoopback(flag) ​

socket.setMulticastTTL(ttl) ​

socket.setRecvBufferSize(size) ​

socket.setSendBufferSize(size) ​

socket.setTTL(ttl) ​

socket.unref() ​

Функции модуля node:dgram ​

dgram.createSocket(options[, callback]) ​

dgram.createSocket(type[, callback]) ​

UDP/датаграммные сокеты

Класс: `dgram.Socket`

Событие: `'close'`

Событие: `'connect'`

Событие: `'error'`

Событие: `'listening'`

Событие: `'message'`

`socket.addMembership(multicastAddress[, multicastInterface])`

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

`socket.address()`

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

`socket.bind(options[, callback])`

`socket.close([callback])`

`socket[Symbol.asyncDispose]()`

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

`socket.disconnect()`

`socket.dropMembership(multicastAddress[, multicastInterface])`

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

`socket.getRecvBufferSize()`

`socket.getSendBufferSize()`

`socket.getSendQueueSize()`

`socket.getSendQueueCount()`

`socket.ref()`

`socket.remoteAddress()`

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

Заметка о размере датаграммы UDP

`socket.setBroadcast(flag)`

`socket.setMulticastInterface(multicastInterface)`

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

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

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

`socket.setMulticastLoopback(flag)`

`socket.setMulticastTTL(ttl)`

`socket.setRecvBufferSize(size)`

`socket.setSendBufferSize(size)`

`socket.setTTL(ttl)`

`socket.unref()`

Функции модуля `node:dgram`

`dgram.createSocket(options[, callback])`

`dgram.createSocket(type[, callback])`