ipfs-swarm

ipfs-swarm Node.js implementation

IPFS swarm implementation in Node.js

Description

ipfs-swarm is an abstraction for the network layer on IPFS. It offers an API to open streams between peers on a specific protocol.

Ref spec (WIP) - https://github.com/diasdavid/specs/blob/protocol-spec/protocol/layers.md#network-layer

Usage

Create a new Swarm

var Swarm = require('ipfs-swarm')
 
var s = new Swarm([port]) // `port` defalts to 4001

Set the swarm to listen for incoming streams

s.listen([port], [callback]) // `port` defaults to 4001, `callback` gets called when the socket starts listening

Close the listener/socket and every open stream that was multiplexed on it

s.closeListener()

Register a protocol to be handled by an incoming stream

s.registerHandler('/name/protocol/you/want/version', function (stream) {})

Open a new connection

Used when we want to make sure we can connect to a given peer, but do not intend to establish a stream with any of the services offered right away.

s.openConnection(peerConnection, function (err) {})

Dial a new stream

s.openStream(peerInfo, protocol, function (err, stream) {})

peerInfo must be a ipfs-peer object, contaning both peer-id and multiaddrs.

Events emitted

.on('error')

.on('connection')
.on('connection-unknown') // used by Identify to start the Identify protocol from listener to dialer

Identify protocol

The Identify protocol is an integral part to Swarm. It enables peers to share observedAddrs, identities and other possible address available. This enables us to do better NAT traversal.

To instantiate Identify:

var Identify = require('ipfs-swarm/identify')

var i = new Identify(swarmInstance, peerSelf)

swarmInstance must be an Instance of swarm and peerSelf must be a instance of ipfs-peer that represents the peer that instantiated this Identify

Identify emits a peer-update event each time it receives information from another peer.