mdns

timeoutMs?: number

Query timeout in milliseconds. Defaults to 2500.

retryMinMs?: number

Minimum delay before retransmitting unanswered one-shot queries. Defaults to 250.

retryMaxMs?: number

Maximum delay before retransmitting unanswered one-shot queries. Defaults to 1000.

settleMs?: number

Additional milliseconds to collect answer bursts after the first packet. Defaults to 20.

bindAddress?: Address

Local UDP address to bind for the query or continuous browse socket.

interfaceAddress?: string

IPv4 interface address used for multicast membership and outbound packets.

interfaceIndex?: number

IPv6 interface index used for multicast membership and outbound packets.

unicastResponse?: boolean

Set the mDNS QU bit to request a unicast response when supported.

knownAnswers?: readonly DnsResourceRecord[]

Known answers to include in outgoing mDNS queries for responder suppression.

cache?: boolean

Use the instance cache for fresh answers. Defaults to true.

validateSource?: boolean

Validate response source addresses against local interface metadata.

localInterfaces?: readonly sock.NetworkInterface[]

Interface metadata used for source validation. Defaults to networkInterfaces().

server?: Address

Override destination for deterministic tests or controlled relays.

signal?: AbortSignal

Abort a long-running query or browse operation.

continuous?: boolean

Keep browse() alive and emit later up/down events.

resolve?: boolean

Resolve service metadata for browse events and emit updates when it changes.

pollMs?: number

Delay between continuous browse refresh queries. Defaults to 1000.

type: 'up' | 'update' | 'down'

Event kind for service lifetime changes.

name: string

Service instance name, such as Printer._http._tcp.local.

serviceType: string

Browsed service type, such as _http._tcp.local.

interfaceIndex: number | null

Interface index when known.

service?: MdnsService

Resolved service metadata when browse runs with resolve: true.

name: string

Service instance name.

target: string

SRV target hostname.

port: number

SRV target port.

txt: Map<string, Uint8Array | true>

DNS-SD TXT attributes keyed case-insensitively.

addresses: string[]

A/AAAA addresses resolved for target.

interfaceIndex: number | null

Interface index when known.

name: string

Instance label without the service type, such as Printer.

serviceType: string

DNS-SD service type, such as _http._tcp.local.

target: string

SRV target hostname.

port: number

SRV target port.

txt?: Record<string, string | Uint8Array | true>

TXT attributes. String values encode as UTF-8; true encodes as a boolean key.

addresses?: string[]

Target A/AAAA addresses.

addressesByInterface?: Record<number, string[]>

Target A/AAAA addresses to use for specific interface indexes.

address?: Address

Bind address for the responder. Defaults to IPv4 mDNS port 5353.

multicast?: boolean

Join the mDNS multicast group for the bound address family. Defaults to true only for the default bind address.

interfaceAddress?: string

IPv4 interface address used for multicast membership and outbound packets.

interfaceIndex?: number

IPv6 interface index used for multicast membership and outbound packets.

probeAddress?: Address

Probe this destination for conflicting service records before publishing.

probeTimeoutMs?: number

Probe response timeout in milliseconds. Defaults to 250.

conflictResolution?: 'reject' | 'rename'

Conflict handling after probing. Defaults to rejecting the publish call.

maxRenameAttempts?: number

Maximum automatic rename attempts when conflictResolution is rename. Defaults to 5.

announceAddress?: Address

Send an unsolicited announcement packet to this destination after binding.

goodbyeAddress?: Address

Send goodbye records to this destination on close in addition to known queriers.

responseDelayMs?: number

Aggregate matching responses for this many milliseconds before sending. Defaults to immediate replies.

readonly address: Address

Bound UDP address for the responder.

readonly name: string

Final DNS-SD service instance name. This may include an automatic rename suffix.

close(): Promise<void>

Stop answering, send goodbye records, and close the UDP socket.

async query( name: string, rrtype: MdnsRecordType, options: MdnsQueryOptions = { } ): Promise<DnsResourceRecord[]>

Send an mDNS query for a name and record type and return the records seen.

The query is transmitted over UDP and the method collects parsed resource records from the answer, authority, and additional sections of every matching response, deduplicated, until either the answer burst settles or the timeout elapses. Unanswered one-shot queries are retransmitted with randomized backoff between retryMinMs and retryMaxMs. When source validation is enabled (the default for multicast destinations), responses from addresses that are not on a local link are ignored. Fresh cached records short-circuit the network round trip unless cache: false or known answers are supplied.

Throws if the client is closed, if the signal is already aborted or aborts during the wait (rejecting with the signal reason), or if no records arrive before the timeout (an Error with code 'ETIMEOUT').

import { Mdns } from 'fino:net/mdns';

const mdns = new Mdns();
const srv = await mdns.query('Printer._http._tcp.local', 'SRV', { timeoutMs: 1500 });
console.log(srv.map((record) => record.data));
await mdns.close();

async resolveHost(name: string, options: MdnsQueryOptions = {}): Promise<string[]>

Resolve a .local hostname to its A/AAAA addresses as strings.

A convenience wrapper over query that asks for A records (or AAAA when the destination server is IPv6), then returns just the address strings from the matching records. Shares the timeout, retry, cache, and error semantics of query, so it throws with code 'ETIMEOUT' when the name does not answer in time.

import { Mdns } from 'fino:net/mdns';

const mdns = new Mdns();
const addresses = await mdns.resolveHost('printer.local');
console.log(addresses); // e.g. ['192.168.1.44']
await mdns.close();

browse(serviceType: string, options: MdnsQueryOptions = {}): AsyncIterable<MdnsBrowseEvent>

Browse a DNS-SD service type, yielding an event per instance lifetime change.

Returns an async iterable of MdnsBrowseEvent. By default it performs one PTR query and yields a single up event per unique instance, then completes. With continuous: true the iterator stays open, repolls every pollMs, ingests unsolicited packets on its bound socket, and additionally emits update when an instance's TTL or (with resolve: true) resolved metadata changes and down when a zero-TTL goodbye record arrives or a TTL lapses. Pass resolve: true to attach a resolved service to up and update events. A continuous iteration ends when the signal aborts or the client is closed; iterating a closed client simply yields nothing.

import { Mdns } from 'fino:net/mdns';

const mdns = new Mdns();
const controller = new AbortController();
for await (const event of mdns.browse('_http._tcp.local', {
  continuous: true,
  resolve: true,
  signal: controller.signal,
})) {
  if (event.type === 'down') console.log('left:', event.name);
  else console.log(event.type, event.name, event.service?.port);
}

async resolveService(instance: string, options: MdnsQueryOptions = {}): Promise<MdnsService>

Resolve a DNS-SD service instance name into a connection target.

Queries the instance's SRV record for its target host and port, then fills in TXT metadata and A/AAAA addresses — preferring records already present in the SRV response's additional section and falling back to follow-up queries for TXT and for the target's addresses when they are absent. The returned MdnsService carries the target, port, parsed TXT map, and resolved addresses.

Throws if the instance has no SRV record (an Error mentioning the instance name), and propagates the timeout error from the underlying SRV query when the instance does not answer.

import { Mdns } from 'fino:net/mdns';

const mdns = new Mdns();
const service = await mdns.resolveService('Printer._http._tcp.local');
console.log(`${service.target}:${service.port}`, service.addresses);
await mdns.close();

async publish( service: MdnsPublishService, options: MdnsPublishOptions = { } ): Promise<MdnsRegistration>

Advertise a DNS-SD service from a built-in responder and return its handle.

Binds a UDP responder that answers PTR, SRV, TXT, A, and AAAA questions for the supplied service, applying duplicate-question suppression and optional response aggregation (responseDelayMs). When multicast publication is active it joins the mDNS group across known interfaces and sends an unsolicited announcement after binding. If probeAddress is set it first probes for a conflicting instance and either rejects or renames according to conflictResolution. The returned MdnsRegistration reports the bound address and the final (possibly renamed) instance name and keeps serving until closed, at which point goodbye records are sent.

Throws if the client is closed, and — when probing finds an unresolved conflict under conflictResolution: 'reject' or after exhausting maxRenameAttempts — an Error with code 'EADDRINUSE'.

import { Mdns } from 'fino:net/mdns';

const mdns = new Mdns();
await using registration = await mdns.publish({
  name: 'Printer',
  serviceType: '_http._tcp.local',
  target: 'printer.local',
  port: 8080,
  txt: { path: '/print' },
  addresses: ['192.168.1.44'],
});
console.log('advertising', registration.name, 'on', registration.address.port);

async close(): Promise<void>

Mark the client closed so further operations are rejected.

The Mdns instance itself owns no persistent sockets — each query opens and closes its own — so closing is cheap and mainly a guard: after it, query, browse, and publish throw. Already-open registrations from publish are independent and must be closed through their own handles. Idempotent and safe to call more than once.

import { Mdns } from 'fino:net/mdns';

const mdns = new Mdns();
try {
  await mdns.resolveHost('printer.local');
} finally {
  await mdns.close();
}