UDP and dgram: datagrams, message boundaries, and when to drop reliability

Datagrams are messages, not a stream

TCP is a reliable, ordered byte stream; UDP is the opposite design point. The dgram module gives you a connectionless socket that sends and receives discrete datagrams — self-contained packets, each routed independently. There is no handshake, no connection state, no ordering, and no acknowledgement. A datagram either arrives whole or not at all.

This flips the framing problem from net on its head. In net you had to add message boundaries because TCP erases them; in dgram the boundaries are preserved for free — one send() produces exactly one 'message' event on the receiver with exactly those bytes. You never get a partial datagram and you never get two coalesced.

const dgram = require("node:dgram");

const server = dgram.createSocket("udp4");
server.on("message", (msg, rinfo) => {
  // msg is one whole datagram; rinfo = { address, port, size }
  console.log(`${rinfo.address}:${rinfo.port} -> ${msg.length} bytes`);
});
server.bind(8125);

const client = dgram.createSocket("udp4");
client.send(Buffer.from("requests:1|c"), 8125, "127.0.0.1");  // fire and forget

Note what is missing: no connect, no accept, no per-client socket object. The server binds a port and receives from anyone; rinfo tells you who sent each datagram. send() is fire-and-forget — its callback fires when the datagram was handed to the OS, not when it was delivered, because UDP has no concept of delivery confirmation.

No delivery, no order, no dedup — by design

Before you reach for UDP, ask yourself: does your protocol actually need every one of TCP’s guarantees, or are you paying for reliability you will never use? The table below makes the tradeoff concrete.

UDP gives you none of TCP’s guarantees, and that is the whole point.

If your application needs reliability or ordering on top of UDP, you implement it (sequence numbers, ACKs, retransmit) — which is exactly what QUIC and reliable-UDP game protocols do. The reason to start from UDP and add only what you need is latency: there is no handshake round trip, no head-of-line blocking (a lost TCP segment stalls everything behind it; a lost datagram affects only itself), and no connection state to manage at scale.

Message size and the MTU cliff

A datagram is bounded. The theoretical IPv4 UDP payload max is 65,507 bytes, but that is not the number that matters in production. The number that matters is the path MTU — typically ~1,500 bytes on Ethernet, often ~1,400 after tunnels/VPNs. A datagram larger than the path MTU must be IP-fragmented into multiple packets, and here is the cliff: if any one fragment is lost, the entire datagram is discarded — IP cannot reassemble a partial datagram. So a 4 KB datagram across a lossy path has a much higher effective loss rate than a 1 KB one, because it is three fragments that must all survive.

The practical rule: keep datagrams under the path MTU — a safe portable target is ~1,200 bytes of payload (the QUIC/DNS guidance). If you need to send more, fragment at the application layer into MTU-sized datagrams with your own sequencing, or use TCP. socket.send() does not split for you against your intent — it hands the whole buffer to the OS, which fragments at the IP layer with the fragility above.

Broadcast and multicast: one send, many receivers

UDP can address groups, which TCP fundamentally cannot. Broadcast sends one datagram to every host on the local subnet (socket.setBroadcast(true), send to the subnet broadcast address) — useful for “is anyone out there?” discovery on a LAN. Multicast is the disciplined version: receivers addMembership(groupAddr) to join a multicast group (224.0.0.0/4), and a single send() to the group address reaches exactly the joined members, with the network duplicating the packet only where paths diverge. setMulticastTTL bounds how many hops it travels. This is how service discovery (mDNS/Bonjour), some clustered-cache gossip, and IPTV-style fan-out work — one send, N receivers, no per-receiver connection.