Eventcast

Network event emitter.

npm install eventcast

Motivation

I decided to write this because 1) multicast is interesting and 2) event emitters are awesome. So it's a learning exercise. And if you think something is amiss - please open an issue!

How it works

Eventcast uses UDP multicast to send BSON-serialized messages to multiple nodes and to receive them. The goal is to provide a network event emitter where nodes can dynamically exchange data via familiar event API.

Checkout example folder to see it in action.

Security

eventcast uses optional aes128 message encryption. Packets encrypted with user-provided passphrase. When encryption is enabled eventcast adds a nonce to every packet (nonce is created using crypto.randomBytes).

Message segmentation

Multicast does not typically support messages over ~1500 bytes as far as I know. Messages that exceed MTU size will be silently dropped. eventcast uses message segmentation for messages larger than maxPayloadSize (defaults to 1024). Message is reassembled on the receiving end.

Packet loss

When receiving segmented messages eventcast will request retransmission of any lost segments (TODO: max number of retransmission requests).

Usage

Create an instance of eventcast and add some events:

var ec1 = Eventcast(9000) // port 9000

ec1.start()

ec1.on('myevent', handleEvent)

var ec2 = Eventcast(9000) // port 9000

ec2.start()

ec2.emit('myevent', 'hello')

REPL

eventcast creates a REPL that provides access to all instance methods and properties. REPL binds to a random port unless replPort is passed to the constructor.

$ telnet localhost 20001
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
eventcast@hostname> eventcast.stop()
true
eventcast>

Configuration

eventcast constructor takes an option hash:

• address string Interface to which UDP server binds. Defaults to 0.0.0.0. Best left unchanged unless you really know what you're doing.
• port number UDP server port. Will be set at random which is not very useful. Port must be the same for instances that want to see each other.
• multicastMembership string Multicast group to join. Defaults to 224.0.0.1 (all hosts).
• multicastInterface string Interface to use for multicast messages. Defaults to 0.0.0.0.
• multicastLoopback boolean Receive multicast messages on the loopback interface. Must be set to true for instances on the same machine to see each other.
• multicastTtl number Multicast scope (see this article). Defaults to 1 - messages will not leave the subnet and will not be forwarded by the router.
• replPort number REPL port. Connect to this port to access built-in REPL. If not set explicitly - port is random (you can figure it out from logs).
• replHost string REPL interface. Defaults to localhost, which is probably best.
• encrypt object Encryption options if you want encryption. By default encryption is disabled.
• encrypt.key string Passphrase to use for encryption. No default.
• maxPayloadSize number Threshold in bytes above which messages will be chunked. Defaults to 1024. Multicast messages are best kept under ~1500 bytes to avoid silent packet loss.
• messageTtl number If chunked message is transmitted and no chunks received within this timeframe - message is discarded. Defaults to 3000 (3 seconds).
• log boolean Enable/disable logging. Default to false.
• logLevel string Log level.

API

Eventcast is an instance of Event Emitter, therefore it supports Event Emitter API. Internally, #emit is the only method that is not real EE method but a wrapper for events.EventEmitter.emit that first sends out messages and then emits the event.

Eventcast#emit(event, [arg1], [arg2], [...])

Sends out event as event with supplied arguments. Arguments must be serializable into JSON because they're going to be sent over the network.

Eventcast#on(event, listener)

Adds a listener for event.

… and the rest of EventEmitter API.

Eventcast#logLevel([component], [level])

(Eventcast uses bunyan to log) If called with no arguments - returns an array of levels for all streams.

Call with level will set all streams to level.

Called with component and level will set that component to given level. Eventcast has two components so far - eventcast and repl. eventcast is the root logger.

Eventcast#start([callback])

Starts the UDP server. callback will be called when server is bound and ready.

Eventcast#stop([callback])

Stops the UDP server. callback will be called when server is shutdown.

Tests

make test

Note that firewall can interfere with tests.