bonjour-hap 3.10.2 → 3.10.3-beta.1

package/index.d.ts

@@ -1,57 +1,144 @@
-import { SocketOptions } from "dgram";
+import { RemoteInfo, Socket } from "dgram";
 
-export type BonjourFindOptions = {
-  type: string;
-  subtypes?: string[];
+/**
+ * Options accepted by the underlying multicast-dns responder.
+ * Forwarded by `Bonjour(options)` straight into `multicast-dns`.
+ */
+export interface MulticastOptions {
+  /** Multicast port. Defaults to 5353. */
+  port?: number;
+  /** Socket type. Defaults to 'udp4'. */
+  type?: "udp4" | "udp6";
+  /** Multicast IP address. Defaults to 224.0.0.251 for udp4. Required for udp6. */
+  ip?: string;
+  /** Alias for `ip`. */
+  host?: string;
+  /** Interface name. Required for IPv6 multicast. */
+  interface?: string;
+  /** Whether to allow address reuse. Defaults to true. */
+  reuseAddr?: boolean;
+  /** Pre-created dgram socket. */
+  socket?: Socket;
+  /** Whether to join the multicast group. Defaults to true. */
+  multicast?: boolean;
+  /** Multicast TTL. Defaults to 255. */
+  ttl?: number;
+  /** Multicast loopback. Defaults to true. */
+  loopback?: boolean;
+  /** Bind address, or `false` to skip binding. */
+  bind?: string | false;
+}
+
+export interface BonjourFindOptions {
+  /** If omitted, performs a wildcard search across all service types. */
+  type?: string;
+  /** Defaults to 'tcp'. */
   protocol?: "tcp" | "udp";
-  txt?: Record<string, any>;
-};
+  /** Filter to a specific service instance name. */
+  name?: string;
+  /** Options forwarded to the TXT record decoder. */
+  txt?: { binary?: boolean };
+}
 
+/**
+ * A service discovered via {@link Bonjour.find} / {@link Bonjour.findOne}.
+ *
+ * Populated from incoming SRV/TXT/A/AAAA records. Services without a matching
+ * SRV record are filtered out before being emitted, so all SRV-derived fields
+ * are guaranteed to be present on emitted services.
+ */
 export interface BonjourService {
   name: string;
+  fqdn: string;
   type: string;
+  subtypes: string[];
   protocol: "tcp" | "udp";
   host: string;
   port: number;
+  referer: RemoteInfo;
   addresses: string[];
-  txt: Record<string, string>;
-  rawTxt?: Buffer;
+  /** Decoded TXT record, if a TXT record was received. */
+  txt?: Record<string, string>;
+  /** Raw TXT record blocks, if a TXT record was received. */
+  rawTxt?: Buffer[];
 }
 
-export interface MulticastOptions extends SocketOptions {
-  multicastAddress?: string;
-  multicastInterface?: string;
-  multicastTTL?: number;
-  reuseAddr?: boolean;
-}
+export interface Browser {
+  /** Currently-known services. Updated as services come up, change, or go down. */
+  services: BonjourService[];
 
-export class Browser {
   start(): void;
   stop(): void;
+  /** Send a fresh PTR query to refresh the service list. */
   update(): void;
-  on(event: "up" | "down", listener: (service: BonjourService) => void): this;
+
+  on(event: "up" | "down" | "update", listener: (service: BonjourService) => void): this;
 }
 
-export class Advertisement {
-  stop(): void;
+/**
+ * A service published via {@link Bonjour.publish}. Returned to the caller so
+ * they can update the TXT record, stop, or destroy the advertisement.
+ */
+export interface Advertisement {
+  name: string;
+  type: string;
+  protocol: "tcp" | "udp";
+  host: string;
+  port: number;
+  fqdn: string;
+  subtypes: string[] | null;
+  txt: Record<string, string> | null;
+  /** True once the initial announcement has been confirmed. */
+  published: boolean;
+
   start(): void;
-  update(txt: Record<string, string>): void;
+  /**
+   * Stop advertising. The callback is required if the service has not been
+   * activated yet (the runtime calls it synchronously in that case).
+   */
+  stop(callback?: () => void): void;
+  /** Tear down the service and remove all listeners. */
+  destroy(): void;
+  /** Replace the TXT record. If `silent` is true, the new record is registered but not re-announced. */
+  updateTxt(txt: Record<string, string>, silent?: boolean): void;
+
+  /** Emitted once after the first successful announcement. */
+  on(event: "up", listener: () => void): this;
+  /** Emitted if the service name is already in use on the network. */
   on(event: "error", listener: (err: Error) => void): this;
 }
 
 export interface PublishOptions {
   name: string;
   type: string;
-  subtypes?: string[];
   port: number;
   host?: string;
-  txt?: Record<string, string>;
   protocol?: "tcp" | "udp";
-}
+  subtypes?: string[];
+  txt?: Record<string, string>;
+  /** Probe for name conflicts before announcing. Defaults to true. */
+  probe?: boolean;
 
-export default class Bonjour {
-  constructor(options?: MulticastOptions);
+  /**
+   * Adds a meta enumeration record (`_services._dns-sd._udp.local`) when announcing.
+   * Only safe to enable when a single service is advertised on the responder, otherwise
+   * removing one service will break enumeration for the others.
+   */
+  addUnsafeServiceEnumerationRecord?: boolean;
 
+  /**
+   * Restricts the service to be advertised on the specified IP addresses or interface names.
+   * Interface names and addresses can be mixed.
+   * If an interface name is given, ANY address on that interface is advertised.
+   * If an IP address is given, only that address is advertised.
+   */
+  restrictedAddresses?: string[];
+
+  /** If true, the service will not advertise IPv6 (AAAA) records. */
+  disabledIpv6?: boolean;
+}
+
+export interface Bonjour {
   publish(options: PublishOptions): Advertisement;
   unpublishAll(callback?: () => void): void;
   find(
@@ -60,7 +147,26 @@ export default class Bonjour {
   ): Browser;
   findOne(
     options: BonjourFindOptions,
-    callback: (service: BonjourService) => void
+    callback?: (service: BonjourService) => void
   ): Browser;
-  destroy(): void;
+  /**
+   * Tear down the responder. Goodbye records are broadcast for every
+   * published service before the underlying mdns socket is closed.
+   * The optional callback fires once teardown is complete.
+   */
+  destroy(callback?: () => void): void;
+  /**
+   * Emitted when the underlying mdns socket reports an error or an
+   * outgoing response fails. If no listener is attached, the error is
+   * logged to `console.warn` so it does not crash the process.
+   */
+  on(event: "error", listener: (err: Error) => void): this;
+}
+
+export interface BonjourFactory {
+  new (options?: MulticastOptions): Bonjour;
+  (options?: MulticastOptions): Bonjour;
 }
+
+declare const Bonjour: BonjourFactory;
+export default Bonjour;

package/index.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const util = require('util')
+const EventEmitter = require('events').EventEmitter
 const Registry = require('./lib/Registry.js')
 const Server = require('./lib/Server.js')
 const Browser = require('./lib/Browser.js')
@@ -7,11 +9,22 @@ const Browser = require('./lib/Browser.js')
 function Bonjour (opts) {
   if (!(this instanceof Bonjour)) { return new Bonjour(opts) }
 
+  EventEmitter.call(this)
+
   this._server = new Server(opts)
   this._registry = new Registry(this._server)
+  this._server.on('error', err => {
+    if (this.listenerCount('error') > 0) {
+      this.emit('error', err)
+    } else {
+      console.warn('bonjour-hap:', err.message || err)
+    }
+  })
 }
 
-Bonjour.prototype = {
+util.inherits(Bonjour, EventEmitter)
+
+Object.assign(Bonjour.prototype, {
   publish: function (opts) {
     return this._registry.publish(opts)
   },
@@ -33,10 +46,12 @@ Bonjour.prototype = {
     return browser
   },
 
-  destroy: function () {
-    this._registry.destroy()
-    this._server.mdns.destroy()
+  destroy: function (cb) {
+    this._registry.destroy(() => {
+      this._server.mdns.destroy()
+      if (cb) cb()
+    })
   }
-}
+})
 
 module.exports = Bonjour

package/lib/Browser.js

@@ -3,6 +3,7 @@
 const util = require('util')
 const EventEmitter = require('events').EventEmitter
 const serviceName = require('multicast-dns-service-types')
+const deepEqual = require('fast-deep-equal')
 const dnsEqual = require('./utils/dnsEqual')
 const dnsTxt = require('./utils/txtDecoder')
 
@@ -35,7 +36,7 @@ function Browser (mdns, opts, onup) {
   this._mdns = mdns
   this._onresponse = null
   this._serviceMap = {}
-  this._txt = dnsTxt(opts.txt)
+  this._txt = dnsTxt(opts && opts.txt)
 
   if (!opts || !opts.type) {
     this._name = WILDCARD
@@ -67,7 +68,7 @@ Browser.prototype.start = function () {
   this._onresponse = function (packet, rinfo) {
     if (self._wildcard) {
       packet.answers.forEach(function (answer) {
-        if (answer.type !== 'PTR' || answer.name !== self._name || answer.name in nameMap) return
+        if (answer.type !== 'PTR' || !dnsEqual(answer.name, self._name) || answer.data in nameMap) return
         nameMap[answer.data] = true
         self._mdns.query(answer.data, 'PTR')
       })
@@ -123,10 +124,19 @@ Browser.prototype._updateService = function (service) {
     return false
   })
   if (!cachedService) return
+  if (!serviceChanged(cachedService, service)) return
   this.services[index] = service
   this.emit('update', service)
 }
 
+function serviceChanged (a, b) {
+  return a.host !== b.host ||
+    a.port !== b.port ||
+    !deepEqual(a.addresses, b.addresses) ||
+    !deepEqual(a.subtypes, b.subtypes) ||
+    !deepEqual(a.txt, b.txt)
+}
+
 Browser.prototype._removeService = function (fqdn) {
   let service, index
   this.services.some(function (s, i) {

package/lib/Prober.js

@@ -30,7 +30,7 @@ Prober.prototype = {
 
   start: function () {
     this.mdns.on('response', this.bound)
-    setTimeout(this.try.bind(this), Math.random() * 250)
+    setTimeout(this.try.bind(this), Math.random() * 250).unref()
   },
 
   try: function () {

package/lib/Registry.js

@@ -26,8 +26,13 @@ Registry.prototype = {
     this._services = []
   },
 
-  destroy: function () {
-    for (let i = 0; i < this._services.length; i++) { this._services[i].destroy() }
+  destroy: function (cb) {
+    const services = this._services.slice()
+    this._services = []
+    this._tearDown(services, () => {
+      for (let i = 0; i < services.length; i++) { services[i].destroy() }
+      if (cb) cb()
+    })
   },
 
   /**
@@ -46,7 +51,7 @@ Registry.prototype = {
 
     const records = services.map(function (service) {
       service.deactivate()
-      const records = service._records(true)
+      const records = service._records()
       records.forEach(function (record) {
         record.ttl = 0 // prepare goodbye message
       })

package/lib/Server.js

@@ -1,17 +1,23 @@
 'use strict'
 
+const util = require('util')
+const EventEmitter = require('events').EventEmitter
 const multicastdns = require('multicast-dns')
 const dnsEqual = require('./utils/dnsEqual')
 const helpers = require('./helpers.js')
 
 const Server = function (opts) {
+  EventEmitter.call(this)
   this.mdns = multicastdns(opts)
   this.mdns.setMaxListeners(0)
   this.registry = {}
   this.mdns.on('query', this._respondToQuery.bind(this))
+  this.mdns.on('error', err => this.emit('error', err))
 }
 
-Server.prototype = {
+util.inherits(Server, EventEmitter)
+
+Object.assign(Server.prototype, {
   _respondToQuery: function (query) {
     for (let i = 0; i < query.questions.length; i++) {
       const question = query.questions[i]
@@ -24,7 +30,7 @@ Server.prototype = {
         ? Object.keys(this.registry).map(this._recordsFor.bind(this, name)).flat()
         : this._recordsFor(name, type)
 
-      if (answers.length === 0) return
+      if (answers.length === 0) continue
 
       // generate the additionals section
       let additionals = []
@@ -57,7 +63,7 @@ Server.prototype = {
         answers,
         additionals
       }, err => {
-        if (err) throw err // TODO: Handle this (if no callback is given, the error will be ignored)
+        if (err) this.emit('error', err)
       })
     }
   },
@@ -89,7 +95,7 @@ Server.prototype = {
       if (!(type in this.registry)) { continue }
 
       this.registry[type] = this.registry[type].filter(r => {
-        return r.name !== record.name
+        return !dnsEqual(r.name, record.name)
       })
     }
   },
@@ -103,6 +109,6 @@ Server.prototype = {
     })
   }
 
-}
+})
 
 module.exports = Server

package/lib/Service.js

@@ -83,7 +83,7 @@ const proto = {
 
   stop: function (cb) {
     if (!this._activated) {
-      cb()
+      if (cb) cb()
       return
     }
 
@@ -109,19 +109,25 @@ const proto = {
     if (this.timer) { clearTimeout(this.timer) }
 
     this.delay = 1000
+    this._emitAnnounce(silent)
+  },
+
+  _emitAnnounce: function (silent) {
+    if (this._destroyed) { return }
     this.emit('service-announce-request', this.packet, silent || false, this.onAnnounceComplete.bind(this))
   },
 
   onAnnounceComplete: function () {
+    if (this._destroyed || !this._activated) return
+
     if (!this.published) {
-      this._activated = true // not sure if this is needed here
       this.published = true
       this.emit('up')
     }
 
     this.delay = this.delay * REANNOUNCE_FACTOR
-    if (this.delay < REANNOUNCE_MAX_MS && !this._destroyed && this._activated) {
-      this.timer = setTimeout(this.announce.bind(this), this.delay).unref()
+    if (this.delay < REANNOUNCE_MAX_MS) {
+      this.timer = setTimeout(this._emitAnnounce.bind(this), this.delay).unref()
     } else {
       this.timer = undefined
       this.delay = undefined
@@ -145,12 +151,12 @@ const proto = {
     this.published = false
   },
 
-  _records: function (teardown) {
+  _records: function () {
     const records = [this._rrPtr(), this._rrSrv(), this._rrTxt()]
 
     records.push(...this._addressRecords())
 
-    if (!teardown && this.addUnsafeServiceEnumerationRecord) {
+    if (this.addUnsafeServiceEnumerationRecord) {
       records.push(this._rrMetaPtr())
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bonjour-hap",
-  "version": "3.10.2",
+  "version": "3.10.3-beta.1",
   "description": "A Bonjour/Zeroconf implementation in pure JavaScript (for HAP)",
   "main": "index.js",
   "types": "index.d.ts",