mirror of
https://github.com/fluencelabs/js-libp2p
synced 2025-06-04 21:21:20 +00:00
83 lines
2.6 KiB
Markdown
83 lines
2.6 KiB
Markdown
ipfs-swarm Node.js implementation
|
|
=================================
|
|
|
|
[](http://ipn.io) [](http://ipfs.io/) [](http://webchat.freenode.net/?channels=%23ipfs) [](https://travis-ci.org/diasdavid/node-ipfs-swarm)
|
|
|
|
> 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
|
|
|
|
```javascript
|
|
var Swarm = require('ipfs-swarm')
|
|
|
|
var s = new Swarm([port]) // `port` defalts to 4001
|
|
```
|
|
|
|
### Set the swarm to listen for incoming streams
|
|
|
|
```javascript
|
|
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
|
|
|
|
```javascript
|
|
s.closeListener()
|
|
```
|
|
|
|
### Register a protocol to be handled by an incoming stream
|
|
|
|
```javascript
|
|
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`](https://www.npmjs.com/package/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.
|