# ut-dns-discovery

> Discovery peers in a distributed system using regular dns and multicast dns.

Latest version **6.2.3** (published 2022-03-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install ut-dns-discovery
pnpm add ut-dns-discovery
yarn add ut-dns-discovery
bun add ut-dns-discovery
```

Provides the command `dns-discovery`.

## 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.2.3 |
| Published | 2022-03-22 |
| First published | 2022-03-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 10 |
| Unpacked size | 60.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Mathias Buus |
| Maintainers | kalin.krustev |

## Links

- npm: https://www.npmjs.com/package/ut-dns-discovery
- Repository: https://github.com/softwaregroup-bg/ut-dns-discovery
- Issues: https://github.com/softwaregroup-bg/ut-dns-discovery/issues
- npm.io page: https://npm.io/package/ut-dns-discovery

## Dependencies (10)

- [lru](https://npm.io/package/lru.md) ^2.0.1
- [pump](https://npm.io/package/pump.md) ^3.0.0
- [debug](https://npm.io/package/debug.md) ^2.6.9
- [minimist](https://npm.io/package/minimist.md) ^1.2.6
- [dns-socket](https://npm.io/package/dns-socket.md) ^4.2.2
- [speedometer](https://npm.io/package/speedometer.md) ^1.1.0
- [multicast-dns](https://npm.io/package/multicast-dns.md) ^7.2.4
- [unordered-set](https://npm.io/package/unordered-set.md) ^1.1.0
- [network-address](https://npm.io/package/network-address.md) ^1.1.2
- [circular-append-file](https://npm.io/package/circular-append-file.md) ^1.0.1

## Recent versions

- 6.2.3 (latest) — 2022-03-22

## README

# dns-discovery

Discovery peers in a distributed system using regular dns and multicast dns.

```
npm install dns-discovery
```

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

## Usage

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

var disc1 = discovery()
var disc2 = discovery()

disc1.on('peer', function (name, peer) {
  console.log(name, peer)
})

// announce an app
disc2.announce('test-app', 9090)
```

## API

#### `var disc = discovery([options])`

Create a new discovery instance. Options include:

``` js
{
  server: 'discovery.example.com:9090', // put a centralized dns discovery server here
  ttl: someSeconds, // ttl for records in seconds. defaults to Infinity.
  limit: someLimit, // max number of records stored. defaults to 10000.
  multicast: true, // use multicast-dns. defaults to true.
  domain: 'my-domain.com', // top-level domain to use for records. defaults to dns-discovery.local
  socket: someUdpSocket, // use this udp socket as the client socket
  loopback: false // discover yourself over multicast
}
```

If you have more than one discovery server you can specify an array

``` js
{
  server: [
    'discovery.example.com:9090',
    'another.discovery.example.com'
  ]
}
```

#### `disc.lookup(name, [callback])`

Do a lookup for a specific app name. When new peers are discovered for this name peer events will be emitted. The callback will be called when the query is complete.

``` js
disc.on('peer', function (name, peer) {
  console.log(name) // app name this peer was discovered for (ie 'example')
  console.log(peer) // {host: 'some-ip', port: 1234}
})
disc.lookup('example')
```

#### `disc.announce(name, port, [options], [callback])`

Announce a new port for a specific app name. Announce also does a lookup so you don't need to do that afterwards.

If you want to specify a public port (a port that is reachable from outside your firewall) you can set the `publicPort: port`
option. This will announce the public port to your list of dns servers and use the other port over multicast.

You can also set `impliedPort: true` to announce the public port of the dns socket to the list of dns servers.

#### `disc.unannounce(name, port, [options], [callback])`

Stop announcing a port for an app. Has the same options as .announce

#### `disc.listen([port], [callback])`

Listen for dns records on a specific port. You *only* need to call this if you want to turn your peer into a discovery server that other peers can use to store peer objects on.

``` js
var server = discovery()
server.listen(9090, function () {
  var disc = discovery({server: 'localhost:9090'})
  disc.announce('test-app', 8080) // will announce this record to the above discovery server
})
```

You can setup a discovery server to announce records on the internet as multicast-dns only works on a local network.
The port defaults to `53` which is the standard dns port. Additionally it tries to bind to `5300` to support networks that filter dns traffic.

#### `disc.destroy([onclose])`

Destroy the discovery instance. Will destroy the underlying udp socket as well.

#### `Event: "listening"`

Emitted after a successful `listen()`.

#### `Event: "close"`

Emitted after a successful `destroy()`.

#### `Event: "peer" (name, {host, port})

Emitted when a peer has been discovered.

 - **name** The app name the peer was discovered for.
 - **host** The address of the peer.
 - **port** The port the peer is listening on.

#### `Event: "announced" (name, {port})`

Emitted after a successful `announce()`.

 - **name** The app name that was announced.
 - **port** The port that was announced.

#### `Event: "unannounced" (name, {port})`

Emitted after a successful `unannounce()`.

 - **name** The app name that was unannounced.
 - **port** The port that was unannounced.

#### `Event: "traffic" (type, details)`

Emitted when any kind of message event occurs. The `type` will be prefixed with `'in:'` to indicate inbound, and `'out:'` to indicate outbound messages. This event is mostly useful for debugging.

#### `Event: "secrets-rotated"`

Emitted when the internal secrets used to generate session tokens have been rotated. This event is mostly useful for debugging.

#### `Event: "error" (err)`

Emitted when networking errors occur, such as failures to bind the socket (EACCES, EADDRINUSE).

## CLI

There is a cli tool available as well

``` sh
npm install -g dns-discovery
dns-discovery help
```

To announce a service do

``` sh
# will announce test-app over multicast-dns
dns-discovery announce test-app --port=8080
```

To look it up

``` sh
# will print services when they are found
dns-discovery lookup test-app
```

To run a discovery server

``` sh
# listen for services and store them with a ttl of 30s
dns-discovery listen --port=9090 --ttl=30
```

And to announce to that discovery server (and over multicast-dns)

``` sh
# replace example.com with the host of the server running the discovery server
dns-discovery announce test-app --server=example.com:9090 --port=9090
```

And finally to lookup using that discovery server (and multicast-dns)

``` sh
dns-discovery lookup test-app --server=example.com:9090
```

You can use any other dns client to resolve the records as well. For example using `dig`.

``` sh
# dig requires the discovery server to run on port 53
dig @discovery.example.com test-app SRV
```

## License

MIT

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