udp-node
Find and communicate with network nodes over UDP.
About
udp-node provides a programatic way of discovering and interacting with other
nodes over UDP. This interaction can be easily achieved using provided methods,
like ping
, broadcast
and onNode
and you can also create your custom events
using the on
and send
methods.
Install
npm install --save udp-node
Sample
In the sample
folder you'll find the basics of finding nodes and sending custom messages.
The code is prepared to run on the same machine by changing default port on one node.
Find all nodes
In this example we will send a broadcast message to find all nodes in the network. These nodes are other instances of udp-node.
const UdpNode = require('udp-node')
const six = new UdpNode()
six
.set({
name: 'Six',
type: 'machine'
})
.broadcast()
.onNode((message, rinfo) => {
// FOUND NODE
// message: contains node's name, type and other details set when node was initialized using set()
// rinfo: contains node's ip address and port
})
This broadcast message is sent to the default port, 3024. Nodes listening on that port will automatically answer with a pong message.
Find specific nodes
When a node is created it can set a type. Then, you can send a broadcast message filtering by type. Nodes belonging to that type are the only ones who will answer with a pong.
const UdpNode = require('udp-node')
const six = new UdpNode()
six
.set({
name: 'Six',
type: 'machine'
})
.broadcast({
filter: ['human']
})
.onNode((message, rinfo) => {
// FOUND HUMAN NODE
})
Properties
guid
A guid is automatically set for each node when the node is constructed.
This means that it will change each time you do new UdpNode()
.
Methods
set(params)
Initializes udp-node. Must be called to start udp client.
Params object:
- name: string, node's name
- type: string, node's type; used on broadcast filter
- port: int, default is 3024
- broadcastAddress: string, default is 255.255.255.255
- logLevel: calls setLogLevel with passed value
broadcast(params)
Sends a broadcast message to the network. Other udp-nodes will respond with a pong message containing their identity.
Params object:
- filter: array, used to get a pong from specific node types
- port: int, default is 3024
- address: string, default is 255.255.255.255
- data: object, custom data to be included in broadcast message
ping(params)
Sends a ping message to a specific udp-node. If that node is available it will respond with a pong message containing its identity.
Params object:
- address: string, required; the address of the node we want to ping; example: 192.168.1.123
- port: int, default is 3024
- data: object, custom data to be included in ping message
send(message, callback)
Sends a custom message.
message
properties:
- type: string, required; this is the message type, not to be confused with node's type
- port: int, default is 3024
- address: string, default is 255.255.255.255
After the message is sent passed callback is called.
onNode(callback)
Called when a node of interest if found, either by a response to our broadcast or ping or when the other node send us a broadcast or ping.
on(type, callback)
Adds a listener for a custom message. When a message of the specified type is recieved calls the passed callback.
CHANGE from previous version:
Returns a ref to this
to allow chaining.
Params:
- type: string, required; any string that identifies the message type
- callback: function, required; called each time a message of specified type is received
off(type, index)
Turns off individual listeners or all listeners for passed message type when index is not provided.
Params:
- type: string, required; any string that identifies the message type
- index: int, identifies a specific listener
setLogLevel(level)
udp-node uses Winston for logging. Please, refer to logging levels on the official documentation for more details.
Params:
- level: string, required; one of: error, warn, info, verbose, debug, silly
close(callback)
Closes UDP socket. Should always be called after finished working with the udp-node to ensure the socket is closed and the port freed up. When the socket is closed calls passed callback.
Notes
If you want to run multiple nodes on the same machine you'll need to provide different ports to each one.
You can easily do this by passing the port
property when calling set()
on each node.