Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mafintosh/discovery-swarm

A network swarm that uses discovery-channel to find peers
https://github.com/mafintosh/discovery-swarm

Last synced: 10 days ago
JSON representation

A network swarm that uses discovery-channel to find peers

Awesome Lists containing this project

README

        

# discovery-swarm

A network swarm that uses [discovery-channel](https://github.com/maxogden/discovery-channel) to find and connect to peers.

This module implements peer connection state and builds on discovery-channel which implements peer discovery. This uses TCP sockets by default and has experimental support for UTP.

```
npm install discovery-swarm
```

[![build status](http://img.shields.io/travis/mafintosh/discovery-swarm.svg?style=flat)](http://travis-ci.org/mafintosh/discovery-swarm)

## Usage

``` js
var swarm = require('discovery-swarm')

var sw = swarm()

sw.listen(1000)
sw.join('ubuntu-14.04') // can be any id/name/hash

sw.on('connection', function (connection) {
console.log('found + connected to peer')
})
```

## API

#### `var sw = swarm(opts)`

Create a new swarm. Options include:
```js
{
id: crypto.randomBytes(32), // peer-id for user
stream: stream, // stream to replicate across peers
connect: fn, // connect local and remote streams yourself
utp: true, // use utp for discovery
tcp: true, // use tcp for discovery
maxConnections: 0, // max number of connections.
whitelist: [], // array of ip addresses to restrict connections to
keepExistingConnections: false // by default, prefer tcp by dropping old utp connections
}
```

For full list of `opts` take a look at [discovery-channel](https://github.com/maxogden/discovery-channel)

#### `sw.join(key, [opts], [cb])`

Join a channel specified by `key` (usually a name, hash or id, must be a **Buffer** or a **string**). After joining will immediately search for peers advertising this key, and re-announce on a timer.

If you pass `opts.announce` as a falsy value you don't announce your port (e.g. you will be in discover-only mode)

If you specify cb, it will be called *when the first round* of discovery has completed. But only on the first round.

#### `sw.leave(key)`

Leave the channel specified `key`

#### `sw.connecting`

Number of peers we are trying to connect to

#### `sw.queued`

Number of peers discovered but not connected to yet

#### `sw.connected`

Number of peers connected to

#### `sw.on('peer', function(peer) { ... })`

Emitted when a peer has been discovered. Peer is an object that contains info about the peer.

```js
{
channel: Buffer('...'), // the channel this connection was initiated on.
host: '127.0.0.1', // the remote address of the peer.
port: 8080, // the remote port of the peer.
id: '192.168.0.5:64374@74657374', // the remote peer's peer-id.
retries: 0 // the number of times tried to connect to this peer.
}
```

#### `sw.on('peer-banned', function(peerAddress, details) { ... })`

Emitted when a peer has been banned as a connection candidate. peerAddress is an object that contains info about the peer. Details is an object that describes the rejection.

```js
{
reason: 'detected-self' // may be 'application' (removePeer() was called) or 'detected-self'
}
```

#### `sw.on('peer-rejected', function(peerAddress, details) { ... })`

Emitted when a peer has been rejected as a connection candidate. peerAddress is an object that contains info about the peer. Details is an object that describes the rejection

```js
{
reason: 'duplicate' // may be 'duplicate', 'banned', or 'whitelist'
}
```

#### `sw.on('drop', function(peer) { ... })`

Emitted when a peer has been dropped from tracking, typically because it failed too many times to connect. Peer is an object that contains info about the peer.

#### `sw.on('connecting', function(peer) { ... })`

Emitted when a connection is being attempted. Peer is an object that contains info about the peer.

#### `sw.on('connect-failed', function(peer, details) { ... })`

Emitted when a connection attempt fails. Peer is an object that contains info about the peer. Details is an object that describes the failure

```js
{
timedout: true // was the failure a timeout?
}
```

#### `sw.on('handshaking', function(connection, info) { ... })`

Emitted when you've connected to a peer and are now initializing the connection's session. Info is an object that contains info about the connection.

``` js
{
type: 'tcp', // the type, tcp or utp.
initiator: true, // whether we initiated the connection or someone else did.
channel: Buffer('...'), // the channel this connection was initiated on. only set if initiator === true.
host: '127.0.0.1', // the remote address of the peer.
port: 8080, // the remote port of the peer.
id: Buffer('...') // the remote peer's peer-id.
}
```

#### `sw.on('handshake-timeout', function(connection, info) { ... })`

Emitted when the handshake fails to complete in a timely fashion. Info is an object that contains info about the connection.

#### `sw.on('connection', function(connection, info) { ... })`

Emitted when you have fully connected to another peer. Info is an object that contains info about the connection.

#### `sw.on('connection-closed', function(connection, info) { ... })`

Emitted when you've disconnected from a peer. Info is an object that contains info about the connection.

#### `sw.on('redundant-connection', function(connection, info) { ... })`

Emitted when multiple connections are detected with a peer, and so one is going to be dropped (the `connection` given). Info is an object that contains info about the connection.

#### `sw.listen(port)`

Listen on a specific port. Should be called before join

## License

MIT