LogoENEnglish

Comprehensive Guide to UDP/Datagram Sockets in Node.js

The node:dgram module provides a full implementation of UDP (User Datagram Protocol) sockets in Node.js. . UDP is a lightweight, connectionless protocol ideal for real‑time applications such as VoIP, gaming, telemetry, IoT, and multicast/broadcast systems. This module exposes APIs for creating sockets, sending and receiving datagrams, joining multicast groups, managing buffer sizes, and controlling low‑level socket behavior.

UDP / Datagramdgram.Socketsocket.bind / socket.sendMulticast / BroadcastTTL / Buffer sizes

~2 دقیقه مطالعه • بروزرسانی ۹ دی ۱۴۰۴

1. Introduction


The node:dgram module enables UDP networking in Node.js. It supports IPv4 and IPv6, multicast, broadcast, and both connectionless and connected UDP modes.


2. Creating a UDP Socket


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

3. Core Events


3.1 'error'


Emitted when any socket error occurs.

3.2 'message'


Emitted when a datagram is received.

3.3 'listening'


Emitted when the socket is bound and ready.

3.4 'close'


Emitted after socket.close() is called.

3.5 'connect'


Emitted after a successful socket.connect() call.


4. Binding a Socket


Binding makes the socket ready to receive datagrams.

socket.bind(41234);

5. Sending Datagrams


UDP supports sending Buffers, strings, TypedArrays, DataViews, or arrays of Buffers.


5.1 Connectionless Send


client.send(message, 41234, 'localhost');

5.2 Connected UDP


client.connect(41234, 'localhost', () => {
  client.send(message);
});

6. Multicast Support


6.1 Joining a Multicast Group


socket.addMembership('224.0.0.114');

6.2 Source‑Specific Multicast


socket.addSourceSpecificMembership(source, group);

6.3 Leaving Multicast Groups


socket.dropMembership(address);
socket.dropSourceSpecificMembership(source, group);

7. Broadcast Support


socket.setBroadcast(true);

8. Buffer and Queue Management


  • socket.getRecvBufferSize()
  • socket.getSendBufferSize()
  • socket.setRecvBufferSize(size)
  • socket.setSendBufferSize(size)
  • socket.getSendQueueSize()
  • socket.getSendQueueCount()

9. TTL and Multicast TTL


  • socket.setTTL(ttl): For unicast.
  • socket.setMulticastTTL(ttl): For multicast.

10. Multicast Interface Selection


Specify outgoing interface for multicast traffic.

socket.setMulticastInterface('10.0.0.2'); // IPv4
socket.setMulticastInterface('::%eth0');  // IPv6

11. Unref and Ref


Control whether the socket keeps the Node.js process alive.

socket.unref();
socket.ref();

12. Blocklists


Block inbound or outbound traffic to specific IPs or ranges.

receiveBlockList: new net.BlockList()
sendBlockList: new net.BlockList()

13. AbortSignal Support


Abort a socket using AbortController.

const controller = new AbortController();
const server = dgram.createSocket({ type: 'udp4', signal: controller.signal });
controller.abort();

14. Datagram Size Limitations


UDP datagrams are limited by MTU and protocol constraints:

  • Max theoretical payload: ~65 KB
  • IPv4 recommended MTU: 576 bytes
  • IPv6 minimum MTU: 1280 bytes

15. dgram.createSocket()


Supports options such as:

  • type: 'udp4' or 'udp6'
  • reuseAddr / reusePort
  • ipv6Only
  • recvBufferSize / sendBufferSize
  • lookup custom DNS resolver
  • signal AbortSignal
  • receiveBlockList / sendBlockList

Conclusion


The node:dgram module provides a complete, low‑level API for building high‑performance UDP applications in Node.js. With support for multicast, broadcast, connected UDP, buffer management, TTL control, blocklists, and AbortSignal integration, it is ideal for real‑time systems, distributed applications, and network‑level tooling.


نوشته و پژوهش شده توسط دکتر شاهین صیامی

Next Article