Skip to content

Latest commit

 

History

History
298 lines (231 loc) · 9.35 KB

README.md

File metadata and controls

298 lines (231 loc) · 9.35 KB
Raw

dnssd.js

Bonjour/Avahi-like service discovery in pure JavaScript

Build Status Coverage Status

dnssd lets you find (and advertise) services on your network like chromecasts, printers, and airplay speakers.

Features

  • Compliant with standards (RFC 6762 & RFC 6763) ✔
  • Won't interfere with existing Bonjour/Avahi installs
  • Handles sleep/hibernate/wakes 💤 without flooding your network
  • Dependency-less
npm install dnssd

Usage

const dnssd = require('dnssd');

// advertise a http server on port 4321
const ad = new dnssd.Advertisement(dnssd.tcp('http'), 4321);
ad.start();

// find all chromecasts
const browser = dnssd.Browser(dnssd.tcp('googlecast'))
  .on('serviceUp', service => console.log("Device up: ", service))
  .on('serviceDown', service => console.log("Device down: ", service))
  .start();

Documentation

dnssd aims to have a API compatible with the mdns package + some extras.


new dnssd.Advertisement(serviceType, port [, options])

// advertising a http server on port 4321:
const ad = new dnssd.Advertisement(dnssd.tcp('http'), 4321);
ad.start();

options.name - instance name
options.host - hostname to use
options.txt - TXT record
options.subtypes - subtypes to register
options.interface - interface name or address to use ('eth0' or '1.2.3.4')

.start()

Starts the advertisement.
If there is a conflict with the instance name it will automatically get renamed. (Name -> Name (2))

.stop([forceImmediately [, callback]])

Stops the advertisement.
Can do either a clean stop or a forced stop. A clean stop will send goodbye records out so others will know the service is going down. This takes ~1s. Forced goodbyes shut everything down immediately.

.on(event, listener)

error
stopped when the advertisement is stopped
instanceRenamed when the service instance has to be renamed
hostRenamed when the hostname has to be renamed

.updateTXT(txt)

Updates the advertisements TXT record

new dnssd.Browser(serviceType [, options])

// find all chromecasts
const browser = dnssd.Browser(dnssd.tcp('googlecast'))
  .on('serviceUp', service => console.log("Device up: ", service))
  .on('serviceDown', service => console.log("Device down: ", service))
  .start();

A resolved service looks like:

service = {
  fullname: 'InstanceName._googlecast._tcp.local.',
  name: 'InstanceName',
  type: { name: 'googlecast', protocol: 'tcp' },
  domain: 'local',
  host: 'Hostname.local.',
  port: 8009,
  addresses: ['192.168.1.15'],
  txt: { id: 'strings' },
  txtRaw: { id: <Buffer XX XX XX... >},
};

Browser search is a multi-step process. First it finds an instance name, then it resolves all the necessary properties of the service, like the address and the port. It keeps that data up to date by sending more queries out as needed. If you want less steps, there's some options:

options.maintain: Set to false if don't want to maintain a service's info. This will give you a 'serviceUp' event but no 'serviceDown' or 'serviceUpdated'

options.resolve: Set to false if you only want the instance name and nothing else.

options.interface: Sets the interface to use ('eth0' or '1.2.3.4')

.start()

Starts the browser.

.stop()

Stops the browser.

.on(event, listener)

error
serviceUp when a new service is found
serviceChanged when a service's data has changed
serviceDown when a service goes down

.list()

Lists all current services that have been found.

new dnssd.ServiceType(...args)

Used to turn some input into a reliable service type for advertisements and browsers. Name and protocol are always required, subtypes are optional. Multiple forms available:

String (single argument)

'_http._tcp'
'_http._tcp,mysubtype,anothersub'

Object (single argument)

{
  name:     '_http',
  protocol: '_tcp',
  subtypes: ['mysubtype', 'anothersub'],
}

Array (single argument)

['_http', '_tcp', ['mysubtype', 'anothersub']]
['_http', '_tcp', 'mysubtype', 'anothersub']

Strings (multiple arguments)

'_http', '_tcp'
'_http', '_tcp', 'mysubtype', 'anothersub'

dnssd.tcp(...args)

Creates a new ServiceType with tcp protocol

ServiceType.tcp('_http')
ServiceType.tcp('_http', 'sub1', 'sub2')
ServiceType.tcp(['_http', 'sub1', 'sub2'])

dnssd.udp(...args)

Creates a new ServiceType with udp protocol

new ServiceType('_services._dns-sd._udp');

dnssd.all()

// browse all the things
const browser = dnssd.Browser(dnssd.all())

dnssd.resolve(name, type [, options])

Async functions for resolving specific records / record types. Returns a promise with result.

dnssd.resolve(name, rrtype).then(function(result) {})
result = {
    answer: {}
    related: [{}, {}]
}

dnssd.resolveA(name [, options])

dnssd.resolveA('something.local.').then((address) => {
  address === '192.168.1.10'
});

dnssd.resolveAAAA(name [, options])

dnssd.resolveAAAA('computer.local.').then((address) => {
  address === '2001:0db8:85a3:0000:0000:8a2e:0370:7334'
});

dnssd.resolveSRV(name [, options])

dnssd.resolveSRV(name).then((srv) => {
  srv === {
      target: 'machine.local.',
      port: 8000,
  }
});

dnssd.resolveTXT(name [, options])

dnssd.resolveTXT(name).then((txt) => {
  txt === { some: 'thing' }
});

dnssd.resolveService(name [, options])

dnssd.resolveService(name).then((service) => {
  service === like the browser results
});

Validations

Service type names and TXT records have some restrictions:

serviceNames:
* must start with an underscore _
* less than 16 chars including the leading _
* must start with a letter or digit
* only letters / digits / hyphens (but not consecutively: --)

TXT records
* Keys <= 9 chars
* Keys must be ascii and can't use '='
* Values must be a string, buffer, number, or boolean
* Each key/value pair must be < 255 bytes
* Total TXT object is < 1300 bytes


License

The MIT License (MIT)

Copyright (c) Sterling DeMille

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.