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);
// Prints: 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);
// Prints: 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()`

Added in: v0.1.99

Returns: <Object>

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

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

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

[История]

Version	Changes
v0.9.1	Метод был изменен на асинхронную модель выполнения. Устаревший код необходимо будет изменить, чтобы передать функцию обратного вызова при вызове метода.
v0.1.99	Added in: 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);
// 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])`

Добавлено в: 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

[Stable: 1 - Experimental]

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

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

`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 не указан или равен 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:

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 обычно расшифровывается как "Time to Live" ("время жизни"), в данном контексте он определяет количество 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 обычно расшифровывается как «Time to Live» (время жизни), в данном контексте она определяет количество 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}`);
});
// Later, when you want to close the server.
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])`