Build your own small (or larger) peer to peer network.

Scale your real-time app with p2p message passing.

  • Simple: Broadcast stuff or just speak to a specific peer.
  • Autonomic: Have your nodes gather and reorder automatically.
  • Flexible: You define, how your nodes will behave.
  • Self-healing: Auto-detection of netsplits and disconnect events.

Smokesignal is not a gossip protocol. It does not implement p2p data replication for you. It is a plain, flexible peer-to-peer networking solution, onto which you can easily build your own replication model or use some event passing mechanism.

To faciliate this, direct connections from peer to peer as well as a network-wide broadcast (Node.broadcast) are simple duplex streams. Thus you can add all favours of stream-goodness, like remote-events, p2p-rpc-stream, and what not.

You can connect to new peers manually or allow your node to search for peers automatically. You can listen on peer list events to get notified when your node added or removed a peer. If you want, your node will automatically ping the network seed(s) once in a while, to detect netsplits and resolve them automatically. Nodes emit a connect event when the node adds the first peer, and a disconnect event, when the last peer disconnects. If you have specified some seeds, your node will automatically rejoin the network in this case.

This project is in development, so be prepared that things might break in some situations.

npm install smokesignal
var smoke = require('smokesignal')
var node = smoke.createNode({
  port: 8495
, address: smoke.localIp('') // Tell it your subnet and it'll figure out the right IP for you 
, seeds: [{port: 13, address:''}] // the address of a seed (a known node) 
// listen on network events... 
node.on('connect', function() {
  // Hey, now we have at least one peer! 
  // ...and broadcast stuff -- this is an ordinary duplex stream! 
  node.broadcast.write('HEYO! I\'m here')
node.on('disconnect', function() {
  // Bah, all peers gone. 
// Broadcast is a stream 
// Start the darn thing 
// mah, i'd rather stop it 

Check out the complete chat app example!

Creates a new node. Options:

  • address: (compulsory) Your current ip address
  • port: (compulsory) Port to bind at
  • minPeerNo: (optional; default: 3) how many peers this node will actively try to bond with -- you can always connect to more manually!
  • `maxPeerNo: (optional; default: 5) how many peers this node will accept at max. Infinity for no limit
  • seeds: (optional) an array of known nodes, that are part of the network, e.g. {port: 0, address: ''}
  • pingTimeout: (optional; default: 3000) The time span in ms after which we consider the ping as failed
  • logger: (optional; default: empty object) An object that may provide the following methods: trace, debug, info, warn, error, fatal

Emitted when we have at least one peer.

Emitted when the last peer disconnects.

A duplex stream. Everyone will get what you write to it, and you'll get everything other people write to it also here.

Starts the node. The tcp server will be bound to the specified port and the node will try to enter the network.

Stops the node. Will disconnect all peers and shut down the tcp server.

Tries to connect to the node at the specified address and add it as a peer. This should allow people to pass a callback..

An instance of Peerlist

Emitted when a peer is added. This event is triggered with the corresponding peer object as the first parameter.

Emitted when a peer is removed. This event is triggered with the corresponding peer object as the first parameter.

Returns a boolean indicating whether you're currently friends with that peer.

An array containing all nodes you're friends with. Please don't manipulate this directly. Instead, use Node#addPeer to try and connect to a node and Peer#close

A duplex stream. Write something to it and the other end will get it out of their representational Peer object for your node. Vice versa, if the other side writes something to their object, you'll be able read it here.

Emitted when all ties to this node have been cut.

The remote address of this peer.

The remote port of this peer.

The network-wide id of this peer.

Cut's everything that ties you to this node.

  • Use event-loop-friendly nextTick call(back)s
  • Maybe make options.port optional, so it just uses an available port

(c) 2012-2013 Marcel Klehr MIT License


  • Correctly inherit from EventEmitter


  • Replace interfaces with proper duplex streams


  • Don't depend on log4js