Federated Node.js Actor Network


Federation is a federated event emitter

Federation is a messaging network built on top of Axon, that lets any two nodes in the federation send routed messages to one and other.


  • fault tolerance
  • zero-configuration setup
  • minimal and familiar api


All federations require a base server. Base servers are zero-configuration:

$ npm install -g federation
$ federation start
Federation Base Started at axon://

Once a base server is established, modify your modules to join the federation.

$ npm install --save federation

In your server.js file add:

var fed  = require('federation').join('axon://');
var node = fed.node(options);

The above node object is a citizen of the network, who can send and receive messages to other nodes.


A federation node operates like an event-emitter.

Send a message:

var launch_code = "12345puppy";

Receive a message:


Messages are sent to address that look like paths, both absolute and relative.

  • absolute path - /america/whitehouse/president
  • relative path - vice-president

Relative paths are resolved to an absolute path based on the address of the sender.

# given the following addresses
/canada/parliament/prime-minister <-- node A
/canada/parliament/house-speaker  <-- node B

# node A can message node B with the address `house-speaker`

Emitted messages can hint at the type of message using a hash-tag (#). Nodes can choose to handle messages according to their hinted type.


The receiving node is planet-express/fry. Fry can catch that message with:


Hinted messages that are not caught will be emitted as message.

You can receive replies to your messages by specifying anonymous handlers:

    // thanks for the money bender!

A receiver can reply to messages by catching a reference to the sender in the handler:

    sender.emit('#reply','THANK YOU');

Multiple anonymous handlers can be registered to the same transaction:

  // handle reply
  // handle error


The specification contains the technical details of the project.

  • federation uses the Axon PubEmitter / SubEmitter socket
  • default port: 8973

Future Features

The following are features that may be cool in a beta release, but are not planned for the alpha.

  • broadcast / multicast addresses
  • multiple addresses