dns-sd-browser 1.0.0

package/lib/index.js

@@ -0,0 +1,252 @@
+/**
+ * dns-sd-browser — Spec-compliant DNS-SD browser over mDNS for Node.js.
+ *
+ * Discovers services advertised via DNS-SD (RFC 6763) over Multicast DNS
+ * (RFC 6762). Designed as a complementary browser to the ciao advertiser.
+ *
+ * @example
+ * ```js
+ * import { DnsSdBrowser } from 'dns-sd-browser'
+ *
+ * const mdns = new DnsSdBrowser()
+ * const browser = mdns.browse('_http._tcp')
+ *
+ * for await (const event of browser) {
+ *   if (event.type === 'serviceUp') {
+ *     console.log(`Found: ${event.service.name} at ${event.service.host}:${event.service.port}`)
+ *   }
+ * }
+ * ```
+ *
+ * @module
+ */
+
+import { MdnsTransport } from './transport.js'
+import { ServiceBrowser, AllServiceBrowser } from './browser.js'
+import { parseServiceType } from './service.js'
+import { SERVICE_TYPE_ENUMERATION, DEFAULT_DOMAIN } from './constants.js'
+
+export { ServiceBrowser, AllServiceBrowser } from './browser.js'
+
+/**
+ * @typedef {import('./service.js').Service} Service
+ * @typedef {import('./browser.js').BrowseEvent} BrowseEvent
+ */
+
+export class DnsSdBrowser {
+  /** @type {MdnsTransport} */
+  #transport
+  /** @type {Set<ServiceBrowser | AllServiceBrowser>} */
+  #browsers = new Set()
+  #started = false
+  #destroyed = false
+  /** @type {Promise<void> | null} */
+  #startPromise = null
+  /** @type {Error | null} */
+  #startError = null
+
+  /**
+   * @param {object} [options]
+   * @param {number} [options.port=5353] - mDNS port
+   * @param {string} [options.interface] - Network interface IP to bind to
+   */
+  constructor(options = {}) {
+    this.#transport = new MdnsTransport({
+      port: options.port,
+      interface: options.interface,
+    })
+  }
+
+  /**
+   * Start browsing for a specific service type.
+   *
+   * Returns a ServiceBrowser that is an async iterable yielding BrowseEvents
+   * as services appear, disappear, or update on the network.
+   *
+   * @param {string | { name: string, protocol?: string }} serviceType
+   *   Service type to browse for. Either a string like "_http._tcp" or
+   *   an object like `{ name: 'http', protocol: 'tcp' }`.
+   * @param {object} [options]
+   * @param {AbortSignal} [options.signal] - Signal to cancel browsing
+   * @param {string} [options.subtype] - Browse a service subtype (RFC 6763 §7.1).
+   *   e.g. `browse('_http._tcp', { subtype: '_printer' })` queries
+   *   `_printer._sub._http._tcp.local`.
+   * @param {number} [options.reconfirmTimeoutMs] - Reconfirmation timeout (ms) per RFC 6762 §10.4
+   * @param {number} [options.poofTimeoutMs] - POOF window (ms) per RFC 6762 §10.5
+   * @param {number} [options.poofResponseWaitMs] - POOF response wait (ms) per RFC 6762 §10.5
+   * @returns {ServiceBrowser}
+   */
+  browse(serviceType, options = {}) {
+    if (this.#destroyed) {
+      throw new Error('DnsSdBrowser has been destroyed')
+    }
+
+    const parsed = parseServiceType(serviceType)
+
+    // Build subtype query name if requested (RFC 6763 §7.1)
+    let queryName = parsed.queryName
+    if (options.subtype) {
+      const sub = options.subtype.startsWith('_') ? options.subtype : `_${options.subtype}`
+      queryName = `${sub}._sub.${parsed.type}.${parsed.domain}`
+    }
+
+    this.#ensureStarted()
+
+    const browser = new ServiceBrowser(this.#transport, {
+      queryName,
+      serviceType: parsed.type,
+      domain: parsed.domain,
+      protocol: parsed.protocol,
+      signal: options.signal,
+      reconfirmTimeoutMs: options.reconfirmTimeoutMs,
+      poofTimeoutMs: options.poofTimeoutMs,
+      poofResponseWaitMs: options.poofResponseWaitMs,
+      onDestroy: () => this.#browsers.delete(browser),
+    })
+
+    this.#browsers.add(browser)
+    return browser
+  }
+
+  /**
+   * Browse for all service instances on the network, regardless of type.
+   *
+   * Discovers service types via `_services._dns-sd._udp.local` (RFC 6763 §9),
+   * then automatically browses each discovered type for instances. Returns
+   * fully resolved BrowseEvents with real host, port, and addresses — the
+   * same as `browse()` but across all types.
+   *
+   * @param {object} [options]
+   * @param {AbortSignal} [options.signal]
+   * @returns {AllServiceBrowser}
+   */
+  browseAll(options = {}) {
+    if (this.#destroyed) {
+      throw new Error('DnsSdBrowser has been destroyed')
+    }
+
+    this.#ensureStarted()
+
+    const browser = new AllServiceBrowser(this.#transport, {
+      domain: DEFAULT_DOMAIN,
+      signal: options.signal,
+      onDestroy: () => this.#browsers.delete(browser),
+    })
+
+    this.#browsers.add(browser)
+    return browser
+  }
+
+  /**
+   * Browse for service types on the network.
+   *
+   * Queries `_services._dns-sd._udp.local` (RFC 6763 §9) to discover
+   * which service types are being advertised. Returns lightweight
+   * Service objects representing types (not instances) — `host`, `port`,
+   * and `addresses` will be empty.
+   *
+   * For discovering fully resolved service instances across all types,
+   * use `browseAll()` instead.
+   *
+   * @param {object} [options]
+   * @param {AbortSignal} [options.signal]
+   * @returns {ServiceBrowser}
+   */
+  browseTypes(options = {}) {
+    if (this.#destroyed) {
+      throw new Error('DnsSdBrowser has been destroyed')
+    }
+
+    this.#ensureStarted()
+
+    const browser = new ServiceBrowser(this.#transport, {
+      queryName: SERVICE_TYPE_ENUMERATION,
+      serviceType: '_services._dns-sd._udp',
+      domain: DEFAULT_DOMAIN,
+      protocol: 'udp',
+      isTypeEnumeration: true,
+      signal: options.signal,
+      onDestroy: () => this.#browsers.delete(browser),
+    })
+
+    this.#browsers.add(browser)
+    return browser
+  }
+
+  /**
+   * Re-join multicast groups and restart all browsers.
+   *
+   * Call this after a network interface change (e.g. WiFi reconnect,
+   * Ethernet re-plug). The OS drops multicast group membership when an
+   * interface goes down; this method re-establishes it and flushes stale
+   * service state.
+   *
+   * All current services are emitted as `serviceDown` events, and
+   * querying restarts with the initial rapid schedule so services on
+   * the new network are discovered quickly.
+   */
+  rejoin() {
+    if (this.#destroyed) throw new Error('DnsSdBrowser has been destroyed')
+    if (!this.#started) return
+
+    this.#transport.rejoinMulticast()
+    for (const browser of this.#browsers) {
+      browser.resetNetwork()
+    }
+  }
+
+  /**
+   * Stop all browsers and close the mDNS transport.
+   * @returns {Promise<void>}
+   */
+  async destroy() {
+    if (this.#destroyed) return
+    this.#destroyed = true
+
+    for (const browser of this.#browsers) {
+      browser.destroy()
+    }
+    this.#browsers.clear()
+
+    // Wait for the transport to finish starting before closing it,
+    // to avoid closing a socket that is still in the process of binding.
+    if (this.#startPromise) {
+      await this.#startPromise.catch(() => {})
+    }
+
+    await this.#transport.destroy()
+  }
+
+  /** @returns {Promise<void>} */
+  async [Symbol.asyncDispose]() {
+    return this.destroy()
+  }
+
+  /**
+   * Returns a promise that resolves when the mDNS transport is ready
+   * to send and receive packets. Useful for tests or when you need
+   * to ensure the socket is bound before external interaction.
+   *
+   * Note: the transport is started lazily on the first `browse()` or
+   * `browseAll()` call. Calling `ready()` before any browse will throw.
+   * @returns {Promise<void>}
+   */
+  async ready() {
+    if (!this.#startPromise) {
+      throw new Error('Cannot call ready() before browse() or browseAll() — transport not started')
+    }
+    await this.#startPromise
+    if (this.#startError) throw this.#startError
+  }
+
+  /** Start the transport if not already started. */
+  #ensureStarted() {
+    if (!this.#started) {
+      this.#started = true
+      this.#startPromise = this.#transport.start().catch((err) => {
+        /* c8 ignore next -- requires a transport bind failure */
+        this.#startError = err
+      })
+    }
+  }
+}

package/lib/service.js

@@ -0,0 +1,152 @@
+/**
+ * Service data type for discovered DNS-SD services.
+ * @module
+ */
+
+/**
+ * @typedef {object} Service
+ * @property {string} name - Instance name (e.g. "My Printer")
+ * @property {string} type - Service type (e.g. "_http._tcp")
+ * @property {string} protocol - Transport protocol ("tcp" or "udp")
+ * @property {string} domain - Domain (default "local")
+ * @property {string} host - Target hostname (e.g. "printer.local")
+ * @property {number} port - Port number
+ * @property {string[]} addresses - IPv4 and IPv6 addresses
+ * @property {Record<string, string | true>} txt - Parsed TXT key-value pairs
+ * @property {Record<string, Uint8Array>} txtRaw - Raw TXT record values
+ * @property {string} fqdn - Fully qualified service name
+ * @property {string[]} subtypes - Service subtypes
+ * @property {number} updatedAt - Timestamp of last update (ms)
+ */
+
+/**
+ * Parse TXT record data (array of Uint8Array strings) into key-value pairs.
+ *
+ * Per RFC 6763 §6.3:
+ * - Format is "key=value" where value is the part after the first '='
+ * - Keys without '=' are boolean flags (value is `true`)
+ * - Duplicate keys: only the first occurrence is used
+ * - Keys are case-insensitive but we preserve original casing
+ *
+ * @param {Uint8Array[]} txtData
+ * @returns {{ txt: Record<string, string | true>, txtRaw: Record<string, Uint8Array> }}
+ */
+export function parseTxtData(txtData) {
+  /** @type {Record<string, string | true>} */
+  const txt = {}
+  /** @type {Record<string, Uint8Array>} */
+  const txtRaw = {}
+  /** @type {Set<string>} - Lowercase keys seen so far for duplicate detection */
+  const seenKeys = new Set()
+  const decoder = new TextDecoder()
+
+  for (const entry of txtData) {
+    const str = decoder.decode(entry)
+    const eqIndex = str.indexOf('=')
+
+    // RFC 6763 §6.4: strings beginning with '=' (missing key) MUST be silently ignored
+    if (eqIndex === 0) continue
+
+    if (eqIndex === -1) {
+      // Boolean flag — key present without value (RFC 6763 §6.4)
+      const key = str
+      const keyLower = key.toLowerCase()
+      if (!seenKeys.has(keyLower)) {
+        seenKeys.add(keyLower)
+        txt[key] = true
+        txtRaw[key] = entry
+      }
+    } else {
+      const key = str.slice(0, eqIndex)
+      const value = str.slice(eqIndex + 1)
+      const keyLower = key.toLowerCase()
+      // Only first occurrence of a key is valid (RFC 6763 §6.4)
+      if (!seenKeys.has(keyLower)) {
+        seenKeys.add(keyLower)
+        txt[key] = value
+        txtRaw[key] = entry.slice(eqIndex + 1)
+      }
+    }
+  }
+
+  return { txt, txtRaw }
+}
+
+/**
+ * Parse a service type string into its components.
+ *
+ * Accepts either:
+ * - Full form: "_http._tcp" or "_http._tcp.local"
+ * - Object form: { name: "http", protocol: "tcp" }
+ *
+ * @param {string | { name: string, protocol?: string }} serviceType
+ * @returns {{ type: string, protocol: string, domain: string, queryName: string }}
+ */
+export function parseServiceType(serviceType) {
+  if (typeof serviceType === 'object') {
+    if (!serviceType || typeof serviceType.name !== 'string' || !serviceType.name) {
+      throw new Error('Service type object must have a non-empty "name" property')
+    }
+    const name = serviceType.name.startsWith('_')
+      ? serviceType.name
+      : `_${serviceType.name}`
+    const protocol = serviceType.protocol || 'tcp'
+    const proto = protocol.startsWith('_') ? protocol : `_${protocol}`
+    const type = `${name}.${proto}`
+    return {
+      type,
+      protocol: proto.slice(1),
+      domain: 'local',
+      queryName: `${type}.local`,
+    }
+  }
+
+  if (typeof serviceType !== 'string' || !serviceType) {
+    throw new Error('Service type must be a non-empty string (e.g. "_http._tcp") or an object { name, protocol? }')
+  }
+
+  // String form: "_http._tcp" or "_http._tcp.local"
+  const parts = serviceType.split('.')
+  let type, domain
+
+  if (parts.length >= 3 && parts[parts.length - 1] === 'local') {
+    // "_http._tcp.local" → type = "_http._tcp", domain = "local"
+    domain = parts[parts.length - 1]
+    type = parts.slice(0, -1).join('.')
+  } else {
+    // "_http._tcp" → default domain "local"
+    type = serviceType
+    domain = 'local'
+  }
+
+  // Extract protocol from type (second label, defaults to tcp)
+  const typeLabels = type.split('.')
+  const protocol = typeLabels.length >= 2 ? typeLabels[1].replace(/^_/, '') : 'tcp'
+
+  return {
+    type,
+    protocol,
+    domain,
+    queryName: `${type}.${domain}`,
+  }
+}
+
+/**
+ * Extract the instance name from a fully qualified service name.
+ *
+ * Given "My Service._http._tcp.local" and type "_http._tcp",
+ * returns "My Service".
+ *
+ * @param {string} fqdn
+ * @param {string} serviceType - e.g. "_http._tcp.local"
+ * @returns {string}
+ */
+export function extractInstanceName(fqdn, serviceType) {
+  // The instance name is everything before the service type
+  const suffix = '.' + serviceType
+  if (fqdn.endsWith(suffix)) {
+    return fqdn.slice(0, -suffix.length)
+  }
+  // Fallback: return the full fqdn
+  return fqdn
+}