@gibme/multicast

A cross-platform multicast/unicast UDP socket library for Node.js (>=22). It abstracts platform-specific details across Windows, Linux, and macOS for IPv4/IPv6 multicast group management, providing a unified EventEmitter-based interface.

Documentation

Full TypeDoc API documentation: https://gibme-npm.github.io/multicast

Features

• IPv4 and IPv6 multicast group support
• Cross-platform: Windows, Linux, and macOS
• Async factory-based creation with full TypeScript types
• Multicast and unicast message sending
• Automatic multi-interface handling:
  • One shared multicast socket bound to 0.0.0.0 / :: for group traffic
  • One dedicated unicast socket per network interface for reliable multi-interface send/receive
• Bind to all interfaces, a specific IP address, or a named interface (e.g. eth0)
• Configurable TTL and multicast loopback
• Partial-failure collection on send (Promise.allSettled semantics)
• fromSelf flag on received messages to identify self-originated traffic

Installation

npm install @gibme/multicast
# or
yarn add @gibme/multicast
Copy

Quick Start

import { MulticastSocket } from '@gibme/multicast';

const socket = await MulticastSocket.create({
    port: 5959,
    multicastGroup: '224.0.0.251',
    loopback: true
});

socket.on('message', (message, local, remote, fromSelf) => {
    console.log({ message: message.toString(), local, remote, fromSelf });
});

const errors = await socket.send(Buffer.from('Hello World'));

if (errors.length > 0) {
    console.error('Send failed on some interfaces:', errors);
}

// when done
await socket.destroy();
Copy

How It Works

When you create a MulticastSocket, the library sets up:

1. One multicast socket bound to 0.0.0.0 (IPv4) or :: (IPv6), joined to the specified multicast group on every selected interface. This socket receives all group traffic.
2. One unicast socket per network interface, each bound to that interface's address. These handle outgoing sends so that each interface transmits independently.

When you call send(), the message goes out on every unicast socket (unless you specify srcAddress). If any individual interface fails, the error is collected and returned — the remaining interfaces still send successfully.

The socket type (udp4 / udp6) is detected automatically from the multicastGroup address.

RFC 6762 §11 (off-link defense)

This library applies both halves of RFC 6762 §11 to defend against off-link injection of multicast traffic (the threat motivates protocols like mDNS):

• Outbound (RFC 6762 §11 first paragraph, SHOULD): every underlying socket (the shared multicast socket and each per-interface unicast socket) is configured with IP_MULTICAST_TTL = 255 and IP_TTL = 255 at bind time. The library does not expose a runtime override — TTL is hardcoded to 255 by design, because the §11 verification on receivers depends on it being exactly 255.
• Inbound (RFC 6762 §11 second paragraph, MUST): received packets are filtered by source address unless linkLocalOnly: false is set. Dropped packets surface as the 'drop' event with reason 'off-link'.

Two important details on the inbound check:

• Approximation, not literal. RFC 6762 §11 specifies the canonical inbound check as IP_TTL === 255 on the received packet. Node's dgram.Socket does not expose the received TTL (no IP_RECVTTL / IPV6_RECVHOPLIMIT ancillary data), so the library uses a source-address subnet check as a no-native-deps interim. A source-address subnet check does not catch on-link-IP source spoofing the way a TTL check would, so this is genuinely weaker than literal §11. There is no plan to work around this — the dgram TTL gap is upstream.
• §11 multicast-destination exemption. Per §11 itself: "All responses received with a destination address in the IP header that is the mDNS IPv4 link-local multicast address 224.0.0.251 or the mDNS IPv6 link-local multicast address FF02::FB are necessarily deemed to have originated on the local link, regardless of source IP address." The library implements this exemption by skipping the source-subnet check on packets received via the shared multicast socket (the only socket joined to the group, and therefore the only socket that receives multicast-destination traffic). Packets received via a per-interface unicast socket — i.e. unicast-destination traffic — still receive the source-subnet check. The trade-off: the exemption permits the cross-subnet-overlay traffic that the spec explicitly addresses, but it relies on multicast routing/switching to keep off-link traffic out of the group. Hosts behind misconfigured multicast routers may receive off-link multicast that the (unavailable) IP_TTL=255 check would have caught.

Disable the inbound filter with linkLocalOnly: false if you need to receive multicast across routed segments deliberately (e.g. SSDP over Layer 3, multicast across VPN tunnels).

API

MulticastSocket.create(options): Promise<MulticastSocket>

Async factory that creates, binds, and returns a new socket.

Options

Option	Type	Default	Description
port	number	(required)	The local port to bind to.
multicastGroup	string	(required)	The multicast group address to join (e.g. '224.0.0.251').
host	string | Address4 | Address6	all interfaces	The local address or interface name to bind to. If omitted, all available interfaces are used. When an IP address is provided, only the matching interface is used. When an interface name is provided (e.g. 'eth0'), all addresses on that interface are used.
loopback	boolean	false	When true, the socket receives its own outgoing multicast packets via the 'message' event (with fromSelf set to true).
reuseAddr	boolean	true	Enables SO_REUSEADDR on the socket.
reusePort	boolean	false	Enables SO_REUSEPORT on the socket (implicitly sets exclusive to true).
exclusive	boolean	false	When true, the socket handle is not shared with cluster workers.
linkLocalOnly	boolean	true	RFC 6762 §11 inbound origin verification. Drops received messages whose source address is not on a local-link subnet of any local interface (loopback is allowed). Dropped packets surface as the 'drop' event. Set to false for receive scenarios that legitimately cross routed segments (e.g. SSDP over Layer 3).

socket.send(message, options?): Promise<Error[]>

Sends a message to the multicast group or a unicast destination. Returns an array of errors for any interfaces that failed (empty on full success). Partial failures do not prevent delivery on other interfaces.

Send Options

Option	Type	Default	Description
useMulticastSocket	boolean	false	Send via the shared multicast socket instead of per-interface unicast sockets.
srcAddress	string | Address4 | Address6	all interfaces	Send from a specific interface only.
dstAddress	string | Address4 | Address6	multicastGroup	Override the destination address (e.g. for unicast replies).
dstPort	number	port	Override the destination port.

socket.destroy(): Promise<void>

Closes all underlying sockets, drops multicast group membership, and removes all event listeners from both the internal sockets and this instance. This is the recommended way to fully tear down a socket.

socket.close(): Promise<void>

Closes all underlying sockets and drops multicast group membership but does not remove event listeners. Prefer destroy() for full cleanup.

socket.setMulticastLoopback(loopback: boolean): void

Sets or clears the IP_MULTICAST_LOOP socket option at runtime.

socket.ref(): void

Adds all underlying sockets back to the Node.js event loop reference count (the default). The process will not exit while the sockets are open.

socket.unref(): void

Removes all underlying sockets from the Node.js event loop reference count, allowing the process to exit while the sockets are still open.

Properties

Property	Type	Description
socket.addresses	string[]	The resolved interface addresses (without CIDR prefix).
socket.interfaces	(Address4 | Address6)[]	The resolved network interfaces as parsed IP address objects.
socket.addressInfo	AddressInfo[]	Address info for all underlying sockets (multicast + unicast).
socket.options	MulticastSocket.Options	The options used to create this socket.

Events

All events pass the local: AddressInfo of the socket that triggered them.

Event	Arguments	Description
message	(message: Buffer, local: AddressInfo, remote: RemoteInfo, fromSelf: boolean)	A UDP message was received and passed all inbound filters. fromSelf indicates whether the message originated from this instance.
drop	(message: Buffer, local: AddressInfo, remote: RemoteInfo, reason: 'off-link')	A received UDP message was rejected by an inbound filter. Currently the only reason is 'off-link' (failed the linkLocalOnly check). Useful for logging or alerting on suspect traffic.
close	(local: AddressInfo)	An underlying socket was closed.
connect	(local: AddressInfo)	An underlying socket connected.
error	(error: Error, local?: AddressInfo)	An underlying socket encountered an error.

Helper Exports

The library re-exports Address4 and Address6 from the ip-address package and provides utility functions:

import {
    MulticastSocket,
    Address4,
    Address6
} from '@gibme/multicast';

import {
    detect_type,
    get_addresses,
    is_valid_ip,
    compare_IP_addresses
} from '@gibme/multicast/helpers';
Copy

Function	Description
detect_type(address)	Returns 'udp4' or 'udp6' for the given IP address string or object. Throws on invalid input.
get_addresses(type, name?)	Returns all non-internal network addresses on the system matching the socket type, with CIDR prefixes. Optionally filter by interface name.
is_valid_ip(address)	Returns an Address4 or Address6 if valid, undefined otherwise.
compare_IP_addresses(a, b)	Numeric comparator for sorting IP addresses (usable with Array.sort()).
is_on_local_link(remote, type)	Returns true if remote is on a local-link subnet of an interface this host owns (or is a loopback / IPv6 link-local address). Used internally by the linkLocalOnly filter; exported so downstream packages can apply the same check on their own dgram paths.

Examples

Listen on a specific interface

const socket = await MulticastSocket.create({
    port: 5959,
    multicastGroup: '224.0.0.251',
    host: '192.168.1.100'
});
Copy

Listen on a named interface

const socket = await MulticastSocket.create({
    port: 5959,
    multicastGroup: '224.0.0.251',
    host: 'eth0'
});
Copy

IPv6 multicast

const socket = await MulticastSocket.create({
    port: 5959,
    multicastGroup: 'ff02::1',
    loopback: true
});
Copy

Send to a specific unicast destination

const errors = await socket.send(Buffer.from('Hello'), {
    dstAddress: '192.168.1.50',
    dstPort: 9000
});
Copy

Send from a specific interface

const errors = await socket.send(Buffer.from('Hello'), {
    srcAddress: '192.168.1.100'
});
Copy

Error handling

socket.on('error', (error, local) => {
    console.error(`Error on ${local?.address}:${local?.port}:`, error.message);
});

const errors = await socket.send(Buffer.from('Hello'));
for (const err of errors) {
    console.warn('Partial send failure:', err.message);
}
Copy

Allow process to exit while socket is open

socket.unref();
Copy

License

MIT