Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mafintosh/dns-discovery
Discovery peers in a distributed system using regular dns and multicast dns.
https://github.com/mafintosh/dns-discovery
Last synced: 9 days ago
JSON representation
Discovery peers in a distributed system using regular dns and multicast dns.
- Host: GitHub
- URL: https://github.com/mafintosh/dns-discovery
- Owner: mafintosh
- License: mit
- Created: 2015-12-27T21:09:46.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2022-03-14T18:26:44.000Z (over 2 years ago)
- Last Synced: 2024-10-23T01:13:56.417Z (16 days ago)
- Language: JavaScript
- Size: 80.1 KB
- Stars: 192
- Watchers: 8
- Forks: 18
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-peer-to-peer - dns-discovery
- awesome-dat - dns-discovery - discover peers using regular- and `multicast-dns` (Dat Core Modules / Networking)
- awesome-network-js - dns-discovery
- awesome-peer-to-peer - dns-discovery
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