# discovery-swarm

> A network swarm that uses discovery-channel to find peers

Latest version **6.1.0** (published 2020-01-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install discovery-swarm
pnpm add discovery-swarm
yarn add discovery-swarm
bun add discovery-swarm
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 6.1.0 |
| Published | 2020-01-21 |
| First published | 2016-02-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 28.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 371 |
| Author | Mathias Buus |
| Maintainers | jhand, karissa, mafintosh, maxogden |

## Links

- npm: https://www.npmjs.com/package/discovery-swarm
- Repository: https://github.com/mafintosh/discovery-swarm
- Issues: https://github.com/mafintosh/discovery-swarm/issues
- npm.io page: https://npm.io/package/discovery-swarm

## Dependencies (7)

- [pump](https://npm.io/package/pump.md) ^3.0.0
- [debug](https://npm.io/package/debug.md) ^4.1.1
- [to-buffer](https://npm.io/package/to-buffer.md) ^1.0.1
- [utp-native](https://npm.io/package/utp-native.md) ^2.1.3
- [connections](https://npm.io/package/connections.md) ^1.4.2
- [discovery-channel](https://npm.io/package/discovery-channel.md) ^5.5.1
- [length-prefixed-message](https://npm.io/package/length-prefixed-message.md) ^3.0.3

## Recent versions

- 6.1.0 (latest) — 2020-01-21
- 6.0.1 — 2019-12-18
- 6.0.0 — 2019-05-29
- 5.1.4 — 2019-01-09
- 5.1.3 — 2018-12-18
- 5.1.2 — 2018-07-06
- 5.1.1 — 2018-03-27
- 5.1.0 — 2018-03-24
- 5.0.0 — 2018-03-15
- 4.4.2 — 2017-07-27
- 4.4.1 — 2017-07-27
- 4.4.0 — 2017-06-11
- 4.3.8 — 2017-05-27
- 4.3.7 — 2017-05-10
- 4.3.6 — 2017-04-30
- … 37 more at https://npm.io/package/discovery-swarm/versions

## 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

---
_Source: https://npm.io/package/discovery-swarm · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._