dgram

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

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

Использование в Deno

import * as mod from "node:dgram";

класс Socket

наследует EventEmitter

Использование в Deno

import { Socket } from "node:dgram";

Совместимость с Deno

Следующие методы являются неработающими заглушками:

addMembership
addSourceSpecificMembership
dropMembership
dropSourceSpecificMembership
setBroadcast
setMulticastInterface
setMulticastLoopback
setMulticastTtl
setTtl

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

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

Методы

[Symbol.asyncDispose](): Promise<void>

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

addListener(

event: string,

listener: (...args: any[]) => void,
): this

events.EventEmitter

close
connect
error
listening
message

addListener(

event: "close",

listener: () => void,
): this

addListener(

event: "connect",

listener: () => void,
): this

addListener(

event: "error",

listener: (err: Error) => void,
): this

addListener(

event: "listening",

listener: () => void,
): this

addListener(

event: "message",

listener: (

msg: Buffer,

rinfo: RemoteInfo,
) => void,
): this

addMembership(

multicastAddress: string,

multicastInterface?: string,
): void

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

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

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

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

if (cluster.isPrimary) {
  cluster.fork(); // Works ok.
  cluster.fork(); // Fails with EADDRINUSE.
} else {
  const s = dgram.createSocket('udp4');
  s.bind(1234, () => {
    s.addMembership('224.0.0.114');
  });
}

addSourceSpecificMembership(

sourceAddress: string,

groupAddress: string,

multicastInterface?: string,
): void

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

address(): AddressInfo

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

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

bind(

port?: number,

address?: string,

callback?: () => void,
): this

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

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

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

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

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

import dgram from 'node:dgram';

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

server.on('error', (err) => {
  console.error(`server error:\n${err.stack}`);
  server.close();
});

server.on('message', (msg, rinfo) => {
  console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`);
});

server.on('listening', () => {
  const address = server.address();
  console.log(`server listening ${address.address}:${address.port}`);
});

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

bind(

port?: number,

callback?: () => void,
): this

bind(callback?: () => void): this

bind(

options: BindOptions,

callback?: () => void,
): this

close(callback?: () => void): this

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

connect(

port: number,

address?: string,

callback?: () => void,
): void

Связывает dgram.Socket с удалённым адресом и портом. Каждое сообщение, отправленное этим дескриптором, автоматически направляется по этому адресу. Кроме того, сокет будет получать сообщения только от этого удалённого узла. Попытка вызвать connect() для уже подключённого сокета приведёт к исключению ERR_SOCKET_DGRAM_IS_CONNECTED. Если address не указан, по умолчанию будут использоваться '127.0.0.1' (для сокетов udp4) или '::1' (для сокетов udp6). После установления соединения генерируется событие 'connect' и вызывается необязательная функция callback. В случае ошибки вызывается callback или, если это невозможно, генерируется событие 'error'.

connect(

port: number,

callback: () => void,
): void

disconnect(): void

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

dropMembership(

multicastAddress: string,

multicastInterface?: string,
): void

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

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

dropSourceSpecificMembership(

sourceAddress: string,

groupAddress: string,

multicastInterface?: string,
): void

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

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

emit(

event: string | symbol,

...args: any[],
): boolean

emit(event: "close"): boolean

emit(event: "connect"): boolean

emit(

event: "error",

err: Error,
): boolean

emit(event: "listening"): boolean

emit(

event: "message",

msg: Buffer,

rinfo: RemoteInfo,
): boolean

getRecvBufferSize(): number

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

getSendBufferSize(): number

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

getSendQueueCount(): number

getSendQueueSize(): number

on(

event: string,

listener: (...args: any[]) => void,
): this

on(

event: "close",

listener: () => void,
): this

on(

event: "connect",

listener: () => void,
): this

on(

event: "error",

listener: (err: Error) => void,
): this

on(

event: "listening",

listener: () => void,
): this

on(

event: "message",

listener: (

msg: Buffer,

rinfo: RemoteInfo,
) => void,
): this

once(

event: string,

listener: (...args: any[]) => void,
): this

once(

event: "close",

listener: () => void,
): this

once(

event: "connect",

listener: () => void,
): this

once(

event: "error",

listener: (err: Error) => void,
): this

once(

event: "listening",

listener: () => void,
): this

once(

event: "message",

listener: (

msg: Buffer,

rinfo: RemoteInfo,
) => void,
): this

prependListener(

event: string,

listener: (...args: any[]) => void,
): this

prependListener(

event: "close",

listener: () => void,
): this

prependListener(

event: "connect",

listener: () => void,
): this

prependListener(

event: "error",

listener: (err: Error) => void,
): this

prependListener(

event: "listening",

listener: () => void,
): this

prependListener(

event: "message",

listener: (

msg: Buffer,

rinfo: RemoteInfo,
) => void,
): this

prependOnceListener(

event: string,

listener: (...args: any[]) => void,
): this

prependOnceListener(

event: "close",

listener: () => void,
): this

prependOnceListener(

event: "connect",

listener: () => void,
): this

prependOnceListener(

event: "error",

listener: (err: Error) => void,
): this

prependOnceListener(

event: "listening",

listener: () => void,
): this

prependOnceListener(

event: "message",

listener: (

msg: Buffer,

rinfo: RemoteInfo,
) => void,
): this

ref(): this

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

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

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

remoteAddress(): AddressInfo

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

send(

msg: 
string
 | ArrayBufferView
 | readonly any[]
,

port?: number,

address?: string,

callback?: (

error: Error | null,

bytes: number,
) => void,
): void

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

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

Аргумент address является строкой. Если значение address — имя хоста, для определения адреса хоста будет использоваться DNS. Если address не задан или имеет значение nullish, по умолчанию будут использоваться '127.0.0.1' (для сокетов udp4) или '::1' (для сокетов udp6).

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

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

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

Смещение и длина необязательны, однако если задан один из этих параметров, необходимо задать и другой. Они поддерживаются только в том случае, если первый аргумент — Buffer, TypedArray или DataView.

При вызове для непривязанного сокета этот метод выбрасывает ERR_SOCKET_BAD_PORT.

Пример отправки UDP-пакета на порт узла localhost:

import dgram from 'node:dgram';
import { Buffer } from 'node:buffer';

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

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

import dgram from 'node:dgram';
import { Buffer } from 'node:buffer';

const buf1 = Buffer.from('Some ');
const buf2 = Buffer.from('bytes');
const client = dgram.createSocket('udp4');
client.send([buf1, buf2], 41234, (err) => {
  client.close();
});

Отправка нескольких буферов может быть быстрее или медленнее в зависимости от приложения и операционной системы. Проведите тесты производительности, чтобы определить оптимальную стратегию для каждого конкретного случая. Однако, как правило, отправка нескольких буферов выполняется быстрее.

Пример отправки UDP-пакета с использованием сокета, подключённого к порту узла localhost:

import dgram from 'node:dgram';
import { Buffer } from 'node:buffer';

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

send(

msg: 
string
 | ArrayBufferView
 | readonly any[]
,

port?: number,

callback?: (

error: Error | null,

bytes: number,
) => void,
): void

send(

msg: 
string
 | ArrayBufferView
 | readonly any[]
,

callback?: (

error: Error | null,

bytes: number,
) => void,
): void

send(

msg: string | ArrayBufferView,

offset: number,

length: number,

port?: number,

address?: string,

callback?: (

error: Error | null,

bytes: number,
) => void,
): void

send(

msg: string | ArrayBufferView,

offset: number,

length: number,

port?: number,

callback?: (

error: Error | null,

bytes: number,
) => void,
): void

send(

msg: string | ArrayBufferView,

offset: number,

length: number,

callback?: (

error: Error | null,

bytes: number,
) => void,
): void

setBroadcast(flag: boolean): void

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

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

setMulticastInterface(multicastInterface: string): void

Все упоминания области действия в этом разделе относятся к индексам зон 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');
});

setMulticastLoopback(flag: boolean): boolean

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

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

setMulticastTTL(ttl: number): number

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

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

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

setRecvBufferSize(size: number): void

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

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

setSendBufferSize(size: number): void

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

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

setTTL(ttl: number): number

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

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

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

unref(): this

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

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

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

функция createSocket

Использование в Deno

import { createSocket } from "node:dgram";

Перегрузка 1

createSocket(

type: SocketType,

callback?: (

msg: Buffer,

rinfo: RemoteInfo,
) => void,
): 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();

Параметры

type: SocketType

callback: (

msg: Buffer,

rinfo: RemoteInfo,
) => void

необязательный

Добавляется как обработчик событий 'message'. Необязательный параметр.

Возвращаемый тип

Socket

Перегрузка 2

createSocket(

options: SocketOptions,

callback?: (

msg: Buffer,

rinfo: RemoteInfo,
) => void,
): Socket

Параметры

options: SocketOptions

callback: (

msg: Buffer,

rinfo: RemoteInfo,
) => void

необязательный

Возвращаемый тип

Socket

интерфейс BindOptions

Использование в Deno

import { type BindOptions } from "node:dgram";

Свойства

port: number | undefined

необязательный

address: string | undefined

необязательный

exclusive: boolean | undefined

необязательный

fd: number | undefined

необязательный

интерфейс RemoteInfo

Использование в Deno

import { type RemoteInfo } from "node:dgram";

Свойства

address: string

family: "IPv4" | "IPv6"

port: number

size: number

интерфейс SocketOptions

расширяет Abortable

Использование в Deno

import { type SocketOptions } from "node:dgram";

Свойства

type: SocketType

reuseAddr: boolean | undefined

необязательный

reusePort: boolean | undefined

необязательный

ipv6Only: boolean | undefined

необязательный

recvBufferSize: number | undefined

необязательный

sendBufferSize: number | undefined

необязательный

lookup: ((

hostname: string,

options: dns.LookupOneOptions,

callback: (

err: ErrnoException | null,

address: string,

family: number,
) => void,
) => void) | undefined

необязательный

receiveBlockList: BlockList | undefined

необязательный

sendBlockList: BlockList | undefined

необязательный

псевдоним типа SocketType

Использование в Deno

import { type SocketType } from "node:dgram";

Определение

"udp4" | "udp6"