Skip to content
actor-ts

UDP

UdpSocketActor wraps a UDP socket — connectionless, no acks, no retries, packet-oriented. Use when best-effort delivery is fine and latency matters more than reliability.

import { ActorSystem, Props, UdpSocketActor } from 'actor-ts';


const udp = system.actorOf(
  Props.create(() => new UdpSocketActor({
    bindHost: '0.0.0.0',
    bindPort: 8125,         // bind for receiving
  })),
  'udp',
);


// Send to a remote endpoint:
udp.tell({
  kind:    'send',
  host:    'collector.example.com',
  port:    8125,
  payload: new TextEncoder().encode('cpu.usage:0.42|g'),
});


// Subscribe to inbound packets:
udp.tell({ kind: 'subscribe', subscriber: packetHandler });

Settings

Section titled “Settings”
interface UdpSocketActorSettings extends BrokerCommonSettings {
  bindHost?: string;             // default '0.0.0.0'; '' to disable receive
  bindPort?: number;             // 0 = random; omit to disable receive
  reuseAddr?: boolean;           // default false
  ipv6Only?: boolean;            // default false
  multicast?: {
    address:   string;
    interface?: string;
    ttl?:      number;
    loopback?: boolean;
  };
}

Send-only

Section titled “Send-only”
new UdpSocketActor({ bindHost: '', bindPort: undefined });   // ✓ send-only

Without bindPort, the actor doesn’t listen — it’s a pure sender. Useful for one-way telemetry (statsd, syslog).

Inbound packets

Section titled “Inbound packets”
class PacketHandler extends Actor<UdpInbound> {
  override onReceive(msg: UdpInbound): void {
    if (msg.kind === 'packet') {
      // msg.payload — Uint8Array
      // msg.from   — { host, port } of the sender
      this.handleDatagram(msg.payload, msg.from);
    }
  }
}

Each packet is one logical message — UDP preserves packet boundaries (unlike TCP’s byte stream).

Multicast

Section titled “Multicast”
new UdpSocketActor({
  bindPort: 5353,
  multicast: {
    address: '224.0.0.251',     // mDNS
    interface: '0.0.0.0',
    ttl: 1,
    loopback: false,
  },
});

Joins the multicast group on the specified interface. Useful for service discovery (mDNS, SSDP), status broadcasting on a LAN.

For routable multicast across cluster nodes, the network must permit multicast (most cloud networks block it; many on-prem networks do too).

When to use UDP

Section titled “When to use UDP”

Three good fits:

  1. Telemetry — sending metrics to a collector (statsd, DogStatsD). Loss of one packet is acceptable; latency matters.
  2. Service discovery on a LAN — mDNS / SSDP / proprietary broadcast schemes.
  3. High-frequency low-stakes data — game positions, sensor streams where the next packet supersedes the previous.

Not the right shape for:

  • Anything that needs delivery guarantee — use TCP, or a higher-level reliable protocol.
  • Anything requiring ordering — UDP packets arrive in any order.
  • Anything larger than MTU — packets >1500 bytes fragment + can drop more easily.

Where to next

Section titled “Where to next”