Comprehensive Guide to UDP/Datagram Sockets in Node.js

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.