Node.js dgram Module Guide

The dgram module provides UDP datagram sockets for connectionless networking. Here's how to use it.

Basic UDP Server#

import dgram from 'node:dgram';

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

server.on('error', (err) => {
  console.error('Server error:', err);
  server.close();
});

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

  // Send response
  const response = Buffer.from('Message received');
  server.send(response, rinfo.port, rinfo.address);
});

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

server.bind(41234);

Basic UDP Client#

import dgram from 'node:dgram';

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

const message = Buffer.from('Hello, server!');

client.send(message, 41234, 'localhost', (err) => {
  if (err) {
    console.error('Send error:', err);
    client.close();
    return;
  }
  console.log('Message sent');
});

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

// Set timeout for response
setTimeout(() => {
  console.log('No response received');
  client.close();
}, 5000);

UDP Echo Server#

import dgram from 'node:dgram';

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

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

  // Echo back the message
  server.send(msg, rinfo.port, rinfo.address, (err) => {
    if (err) console.error('Echo error:', err);
  });
});

server.bind(41234, () => {
  console.log('Echo server running on port 41234');
});

IPv6 Support#

import dgram from 'node:dgram';

// IPv6 socket
const server6 = dgram.createSocket('udp6');

server6.on('message', (msg, rinfo) => {
  console.log(`IPv6 message: ${msg} from [${rinfo.address}]:${rinfo.port}`);
});

server6.bind(41234, '::', () => {
  console.log('IPv6 server running');
});

// Dual-stack socket (IPv4 and IPv6)
const dualStack = dgram.createSocket({
  type: 'udp6',
  ipv6Only: false,
});

dualStack.bind(41235, () => {
  console.log('Dual-stack server running');
});

Multicast#

import dgram from 'node:dgram';

const MULTICAST_ADDR = '224.1.1.1';
const PORT = 5000;

// Multicast sender
function createSender() {
  const sender = dgram.createSocket('udp4');

  setInterval(() => {
    const message = Buffer.from(`Time: ${Date.now()}`);
    sender.send(message, PORT, MULTICAST_ADDR, (err) => {
      if (err) console.error('Multicast send error:', err);
    });
  }, 1000);

  return sender;
}

// Multicast receiver
function createReceiver() {
  const receiver = dgram.createSocket({
    type: 'udp4',
    reuseAddr: true,
  });

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

  receiver.bind(PORT, () => {
    receiver.addMembership(MULTICAST_ADDR);
    console.log('Joined multicast group');
  });

  return receiver;
}

const sender = createSender();
const receiver = createReceiver();

Broadcast#

import dgram from 'node:dgram';

const BROADCAST_ADDR = '255.255.255.255';
const PORT = 5001;

// Broadcast sender
function createBroadcaster() {
  const socket = dgram.createSocket('udp4');

  socket.bind(() => {
    socket.setBroadcast(true);

    setInterval(() => {
      const message = Buffer.from('Broadcast message');
      socket.send(message, PORT, BROADCAST_ADDR, (err) => {
        if (err) console.error('Broadcast error:', err);
      });
    }, 1000);
  });

  return socket;
}

// Broadcast receiver
function createBroadcastReceiver() {
  const socket = dgram.createSocket({
    type: 'udp4',
    reuseAddr: true,
  });

  socket.on('message', (msg, rinfo) => {
    console.log(`Broadcast received: ${msg} from ${rinfo.address}`);
  });

  socket.bind(PORT);

  return socket;
}

Socket Options#

import dgram from 'node:dgram';

const socket = dgram.createSocket({
  type: 'udp4',
  reuseAddr: true,        // Allow multiple sockets on same port
  recvBufferSize: 65536,  // Receive buffer size
  sendBufferSize: 65536,  // Send buffer size
});

socket.bind(41234, () => {
  // Set TTL (Time To Live)
  socket.setTTL(128);

  // Set multicast TTL
  socket.setMulticastTTL(2);

  // Enable multicast loopback
  socket.setMulticastLoopback(true);

  // Get/set receive buffer size
  console.log('Recv buffer:', socket.getRecvBufferSize());
  socket.setRecvBufferSize(131072);

  // Get/set send buffer size
  console.log('Send buffer:', socket.getSendBufferSize());
  socket.setSendBufferSize(131072);
});

Message Framing#

import dgram from 'node:dgram';

// Simple message protocol
class UDPProtocol {
  constructor(socket) {
    this.socket = socket;
    this.handlers = new Map();
  }

  // Send structured message
  send(type, data, port, address) {
    const message = JSON.stringify({ type, data });
    const buffer = Buffer.from(message);

    return new Promise((resolve, reject) => {
      this.socket.send(buffer, port, address, (err) => {
        if (err) reject(err);
        else resolve();
      });
    });
  }

  // Register message handler
  on(type, handler) {
    this.handlers.set(type, handler);
  }

  // Process incoming messages
  listen() {
    this.socket.on('message', (msg, rinfo) => {
      try {
        const { type, data } = JSON.parse(msg.toString());
        const handler = this.handlers.get(type);
        if (handler) {
          handler(data, rinfo);
        }
      } catch (err) {
        console.error('Parse error:', err);
      }
    });
  }
}

// Usage
const socket = dgram.createSocket('udp4');
const protocol = new UDPProtocol(socket);

protocol.on('ping', (data, rinfo) => {
  console.log('Ping received from', rinfo.address);
  protocol.send('pong', { time: Date.now() }, rinfo.port, rinfo.address);
});

protocol.on('pong', (data, rinfo) => {
  console.log('Pong received:', data.time);
});

protocol.listen();
socket.bind(41234);

Service Discovery#

import dgram from 'node:dgram';
import os from 'node:os';

const DISCOVERY_PORT = 5002;
const MULTICAST_ADDR = '224.0.0.1';

class ServiceDiscovery {
  constructor(serviceName, servicePort) {
    this.serviceName = serviceName;
    this.servicePort = servicePort;
    this.socket = dgram.createSocket({
      type: 'udp4',
      reuseAddr: true,
    });
    this.peers = new Map();
  }

  start() {
    this.socket.on('message', (msg, rinfo) => {
      try {
        const data = JSON.parse(msg.toString());
        this.handleMessage(data, rinfo);
      } catch (err) {
        // Ignore invalid messages
      }
    });

    this.socket.bind(DISCOVERY_PORT, () => {
      this.socket.addMembership(MULTICAST_ADDR);
      this.socket.setBroadcast(true);

      // Announce presence
      this.announce();

      // Periodic announcements
      setInterval(() => this.announce(), 5000);

      // Clean up stale peers
      setInterval(() => this.cleanupPeers(), 10000);
    });
  }

  announce() {
    const message = JSON.stringify({
      type: 'announce',
      service: this.serviceName,
      port: this.servicePort,
      hostname: os.hostname(),
    });

    this.socket.send(
      Buffer.from(message),
      DISCOVERY_PORT,
      MULTICAST_ADDR
    );
  }

  handleMessage(data, rinfo) {
    if (data.type === 'announce') {
      const key = `${rinfo.address}:${data.port}`;
      this.peers.set(key, {
        address: rinfo.address,
        port: data.port,
        service: data.service,
        hostname: data.hostname,
        lastSeen: Date.now(),
      });
    }
  }

  cleanupPeers() {
    const now = Date.now();
    for (const [key, peer] of this.peers) {
      if (now - peer.lastSeen > 15000) {
        this.peers.delete(key);
        console.log('Peer removed:', key);
      }
    }
  }

  getPeers() {
    return Array.from(this.peers.values());
  }
}

// Usage
const discovery = new ServiceDiscovery('my-app', 8080);
discovery.start();

setInterval(() => {
  console.log('Known peers:', discovery.getPeers());
}, 5000);

UDP with Promises#

import dgram from 'node:dgram';

class UDPClient {
  constructor() {
    this.socket = dgram.createSocket('udp4');
    this.pending = new Map();
    this.messageId = 0;

    this.socket.on('message', (msg, rinfo) => {
      try {
        const data = JSON.parse(msg.toString());
        const pending = this.pending.get(data.id);
        if (pending) {
          clearTimeout(pending.timeout);
          this.pending.delete(data.id);
          pending.resolve(data.response);
        }
      } catch (err) {
        // Ignore parse errors
      }
    });
  }

  send(message, port, address, timeout = 5000) {
    return new Promise((resolve, reject) => {
      const id = ++this.messageId;

      const timeoutId = setTimeout(() => {
        this.pending.delete(id);
        reject(new Error('Request timeout'));
      }, timeout);

      this.pending.set(id, {
        resolve,
        reject,
        timeout: timeoutId,
      });

      const data = JSON.stringify({ id, request: message });
      this.socket.send(Buffer.from(data), port, address, (err) => {
        if (err) {
          clearTimeout(timeoutId);
          this.pending.delete(id);
          reject(err);
        }
      });
    });
  }

  close() {
    this.socket.close();
  }
}

// Usage
const client = new UDPClient();

async function main() {
  try {
    const response = await client.send(
      { action: 'getData' },
      41234,
      'localhost'
    );
    console.log('Response:', response);
  } catch (err) {
    console.error('Error:', err.message);
  } finally {
    client.close();
  }
}

Error Handling#

import dgram from 'node:dgram';

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

socket.on('error', (err) => {
  console.error('Socket error:', err.message);

  // Handle specific errors
  switch (err.code) {
    case 'EADDRINUSE':
      console.log('Port already in use');
      break;
    case 'EACCES':
      console.log('Permission denied');
      break;
    case 'ENETUNREACH':
      console.log('Network unreachable');
      break;
    default:
      console.log('Unknown error:', err.code);
  }

  socket.close();
});

socket.on('close', () => {
  console.log('Socket closed');
});

// Graceful shutdown
process.on('SIGINT', () => {
  console.log('Shutting down...');
  socket.close(() => {
    process.exit(0);
  });
});

socket.bind(41234);

Best Practices#

Socket Configuration:
✓ Use reuseAddr for multiple listeners
✓ Set appropriate buffer sizes
✓ Handle all error events
✓ Clean up on close

Message Handling:
✓ Validate incoming data
✓ Implement timeouts
✓ Handle partial messages
✓ Use sequence numbers

Multicast:
✓ Join/leave groups properly
✓ Set appropriate TTL
✓ Handle loopback
✓ Use reuseAddr

Avoid:
✗ Ignoring errors
✗ Assuming delivery
✗ Large datagrams (>512 bytes safe)
✗ Blocking operations

The Node.js dgram module provides UDP networking for connectionless communication. Use it for real-time applications, service discovery, broadcasts, and multicast scenarios where occasional packet loss is acceptable. Always handle errors, implement timeouts for request-response patterns, and keep messages small for reliable delivery. For guaranteed delivery or streaming data, consider TCP with the net module instead.