/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { AsyncCache, describeList, Diagnostic, DnsMessageType, DnsMessageTypeFlag, DnsRecord, DnsRecordType, Instant, isDeepEqual, Lifetime, Logger, MatterAggregateError, MdnsSocket, Millis, Minutes, NetworkInterfaceDetails, ObserverGroup, Time, Timer, Timestamp, } from "@matter/general"; const logger = Logger.get("MdnsServer"); const RESPONDER_NAMES_OWNER = "mdns-responder"; /** RFC 6762 §7.3 - Window for duplicate question suppression (999ms per python-zeroconf) */ export const QUESTION_SUPPRESSION_WINDOW = Millis(999); export class MdnsServer { #lifetime: Lifetime; #observers = new ObserverGroup(); #recordsGenerator = new Map(); readonly #records: AsyncCache; // Union of advertised names across interfaces, fed to the socket so it keeps queries for our records (notably // bare-hostname A/AAAA queries, which carry no service-type label) before decoding. Reset when records change. readonly #responderNames = new Set(); #hostname?: string; readonly #recordLastSentAsMulticastAnswer = new Map(); readonly #truncatedQueryCache = new Map(); /** RFC 6762 §7.3 - Tracks recently answered queries for duplicate suppression */ readonly #recentlyAnsweredQueries = new Map< string, { knownAnswerHashes: Set; timestamp: Timestamp; } >(); readonly #socket: MdnsSocket; constructor(socket: MdnsSocket, lifetime = Lifetime.process) { this.#socket = socket; this.#lifetime = lifetime.join("mdns server"); this.#records = new AsyncCache( "MDNS discovery", this.#lifetime, async (multicastInterface: string) => { const byService = new Map[]>(); const ownedNames = new Set(); const addrs = await this.network.getIpMac(multicastInterface); if (addrs === undefined) { return { byService, ownedNames }; } const hostname = this.#hostname ?? hostnameForMac(addrs.mac); for (const [service, generator] of this.#recordsGenerator) { const records = generator(multicastInterface, addrs, hostname); byService.set(service, records); for (const record of records) { ownedNames.add(record.name.toLowerCase()); } } this.#registerResponderNames(ownedNames); return { byService, ownedNames }; }, Minutes(15) /* matches maximum standard commissioning window time */, ); this.#observers.on(this.#socket.receipt, this.#handleMessage.bind(this)); } get network() { return this.#socket.network; } get supportsIpv4() { return this.#socket.supportsIpv4; } buildDnsRecordKey(record: DnsRecord, netInterface?: string, unicastTarget?: string) { return `${record.name.toLowerCase()}-${record.recordClass}-${record.recordType}-${netInterface}-${unicastTarget}`; } async #handleMessage(incomingMessage: MdnsSocket.Message) { using _processing = this.#lifetime.join("processing message"); const { byService, ownedNames } = await this.#records.get(incomingMessage.sourceIntf); // Ignore if we have no records for interface if (byService.size === 0) { return; } const message = this.#prepareMessage(incomingMessage); if (message === undefined) { return; } const { sourceIntf, sourceIp, transactionId, queries, answers: knownAnswers } = message; // Skip unrelated LAN traffic; run after #prepareMessage so TC continuations are first merged. if (!queries.some(q => ownedNames.has(q.name.toLowerCase()))) { return; } let sentPreviousPacket = false; for (const portRecords of byService.values()) { let answers = queries.flatMap(query => this.#queryRecords(query, portRecords)); if (answers.length === 0) continue; // Only send additional records if the query is not for A or AAAA records let additionalRecords = queries.find( query => query.recordType !== DnsRecordType.A && query.recordType !== DnsRecordType.AAAA, ) !== undefined ? portRecords.filter(record => !answers.includes(record) && record.recordType !== DnsRecordType.PTR) : []; if (knownAnswers.length > 0) { for (const knownAnswersRecord of knownAnswers) { answers = answers.filter(record => !this.#suppressedByKnownAnswer(record, knownAnswersRecord)); if (answers.length === 0) break; // Nothing to send } if (answers.length === 0) continue; // Nothing to send if (additionalRecords.length > 0) { for (const knownAnswersRecord of knownAnswers) { additionalRecords = additionalRecords.filter( record => !this.#suppressedByKnownAnswer(record, knownAnswersRecord), ); } } } const now = Time.nowMs; let uniCastResponse = queries.filter(query => !query.uniCastResponse).length === 0; const answersTimeSinceLastSent = answers.map(answer => ({ timeSinceLastMultiCast: Millis( now - (this.#recordLastSentAsMulticastAnswer.get(this.buildDnsRecordKey(answer, sourceIntf)) ?? 0), ), ttl: answer.ttl, })); if ( uniCastResponse && answersTimeSinceLastSent.some(({ timeSinceLastMultiCast, ttl }) => timeSinceLastMultiCast > ttl / 4) ) { // If the query is for unicast response, still send as multicast if they were last sent as multicast longer then 1/4 of their ttl uniCastResponse = false; } if (!uniCastResponse) { answers = answers.filter( // The last time sent as multicast was more than 900 ms ago (_, index) => answersTimeSinceLastSent[index].timeSinceLastMultiCast >= Millis(900), ); if (answers.length === 0) continue; // Nothing to send // RFC 6762 §7.3 - Check for duplicate question suppression if (this.#shouldSuppressResponse(queries, knownAnswers, sourceIntf, answers)) { continue; // Another responder already answered } answers.forEach(answer => this.#recordLastSentAsMulticastAnswer.set(this.buildDnsRecordKey(answer, sourceIntf), now), ); } if (sentPreviousPacket) { await Time.sleep("MDNS delay", Millis(20 + Math.floor(Math.random() * 100))); } this.#socket .send( { messageType: DnsMessageType.Response, transactionId, answers: sendable(answers, portRecords, uniCastResponse), additionalRecords: sendable(additionalRecords, portRecords, uniCastResponse), }, sourceIntf, uniCastResponse ? sourceIp : undefined, ) .catch(error => { logger.warn(`Failed to send mDNS response to ${sourceIp}`, error); }); sentPreviousPacket = true; } } async #announceRecordsForInterface(netInterface: string, records: DnsRecord[]) { // RFC 6762 §8.3: announcements carry all records in the answer section await this.#socket.send( { messageType: DnsMessageType.Response, answers: records, }, netInterface, ); } async broadcast(...services: string[]) { using _broadcasting = this.#lifetime.join("broadcasting", Diagnostic.strong(describeList("and", ...services))); await MatterAggregateError.allSettled( (await this.#getMulticastInterfacesForAnnounce()).map(async ({ name: netInterface }) => { const { byService } = await this.#records.get(netInterface); let sentPreviousPacket = false; for (const [service, serviceRecords] of byService) { if (services.length && !services.includes(service)) continue; if (sentPreviousPacket) { await Time.sleep("MDNS delay", Millis(20 + Math.floor(Math.random() * 100))); } await this.#announceRecordsForInterface(netInterface, serviceRecords); sentPreviousPacket = true; } }), "Error announcing MDNS messages", ).catch(error => { if (this.#lifetime.isClosing) { logger.debug("Error announcing MDNS messages while closing", error); } else { logger.error("Error announcing MDNS messages", error); } }); } async expireAnnouncements(...services: string[]) { using _expiring = this.#lifetime.join("expiring", Diagnostic.strong(describeList("and", ...services))); await MatterAggregateError.allSettled( this.#records.keys().map(async netInterface => { const { byService } = await this.#records.get(netInterface); let sentPreviousPacket = false; for (const [service, serviceRecords] of byService) { if (services.length && !services.includes(service)) continue; // Set TTL to Instant for all records to expire them serviceRecords.forEach(record => { record.ttl = Instant; }); if (sentPreviousPacket) { await Time.sleep("MDNS delay", Millis(20 + Math.floor(Math.random() * 100))); } await this.#announceRecordsForInterface(netInterface, serviceRecords); this.#recordsGenerator.delete(service); sentPreviousPacket = true; } }), "Error happened when expiring MDNS announcements", ).catch(error => { if (this.#lifetime.isClosing) { logger.debug("Error happened when expiring MDNS announcements while closing", error); } else { logger.warn("Error happened when expiring MDNS announcements", error); } }); await this.#resetServices(); } async setRecordsGenerator(service: string, generator: MdnsServer.RecordGenerator) { this.#recordsGenerator.set(service, generator); await this.#resetServices(); } async #resetServices() { await this.#chooseHostname(); await this.#records.clear(); this.#recordLastSentAsMulticastAnswer.clear(); this.#recentlyAnsweredQueries.clear(); // Reset the accumulator but leave the prior footprints registered until the cache rebuilds and replaces them: // an empty registration here would open a window where queries for our own hostname get dropped, while stale // footprints only ever cause a harmless extra decode. this.#responderNames.clear(); } // Accumulate the union of advertised names across interfaces; re-register only when it grows. Stale entries from a // vanished interface are at worst extra keeps and are cleared on the next #resetServices. #registerResponderNames(ownedNames: Iterable) { let changed = false; for (const name of ownedNames) { if (!this.#responderNames.has(name)) { this.#responderNames.add(name); changed = true; } } if (changed) { this.#socket.registerRelevantNames(RESPONDER_NAMES_OWNER, this.#responderNames); } } async close() { using _closing = this.#lifetime.closing(); this.#observers.close(); this.#socket.unregisterRelevantNames(RESPONDER_NAMES_OWNER); await this.#records.close(); for (const { timer } of this.#truncatedQueryCache.values()) { timer.stop(); } this.#truncatedQueryCache.clear(); this.#recordLastSentAsMulticastAnswer.clear(); this.#recentlyAnsweredQueries.clear(); } /** * Chooses the target host name of every interface: the current one while an interface still carries its MAC, * otherwise the first interface with addresses and a non-zero MAC. * * A querier that hears us on several interfaces must see one host per instance, so the name may not follow the * interface; the Matter specification permits one host name across interfaces (Core, "Host Name Construction"). */ async #chooseHostname() { try { const candidates = new Array(); for (const { name } of await this.#getMulticastInterfacesForAnnounce()) { let details; try { details = await this.network.getIpMac(name); } catch (error) { logger.debug(`Interface ${name} skipped for the mDNS host name`, error); continue; } if (details?.ipV4.length || details?.ipV6.length) { if (/[1-9a-f]/i.test(details.mac)) { candidates.push(hostnameForMac(details.mac)); } } } if (this.#hostname === undefined || !candidates.includes(this.#hostname)) { this.#hostname = candidates[0]; } } catch (error) { logger.warn("Cannot list network interfaces to choose the mDNS host name", error); } } #getMulticastInterfacesForAnnounce() { const { netInterface } = this.#socket; return netInterface === undefined ? this.network.getNetInterfaces() : [{ name: netInterface }]; } /** * Whether a querier's known answer already carries {@link record}. * * A record is identified by its name, type, class and value; the cache-flush bit is framing, meaningful only in a * response. A known answer suppresses only while more than half its lifetime remains. * * @see {@link https://www.rfc-editor.org/rfc/rfc6762#section-7.1} RFC 6762 §7.1 */ #suppressedByKnownAnswer(record: DnsRecord, knownAnswer: DnsRecord): boolean { // Cheapest discriminators first: this runs once per (answer, known answer) pair on every inbound query return ( record.recordType === knownAnswer.recordType && record.recordClass === knownAnswer.recordClass && knownAnswer.ttl > record.ttl / 2 && sameName(record.name, knownAnswer.name) && isDeepEqual(record.value, knownAnswer.value) ); } #queryRecords({ name, recordType }: { name: string; recordType: DnsRecordType }, records: DnsRecord[]) { // DNS names are case-insensitive per RFC 6762 §16 / RFC 1035 §2.3.3. const queryName = name.toLowerCase(); if (recordType === DnsRecordType.ANY) { return records.filter(record => record.name.toLowerCase() === queryName); } else { return records.filter( record => record.name.toLowerCase() === queryName && record.recordType === recordType, ); } } /** * RFC 6762 §7.3 - Checks if we should suppress a response because another responder * has recently answered the same question with answers that cover what we'd send. * Also, lazily cleans up expired entries from the cache. */ #shouldSuppressResponse( queries: { name: string; recordType: DnsRecordType }[], knownAnswers: DnsRecord[], sourceIntf: string, answers: DnsRecord[], ): boolean { const now = Time.nowMs; // Clean up expired entries for (const [key, entry] of this.#recentlyAnsweredQueries) { if (now - entry.timestamp >= QUESTION_SUPPRESSION_WINDOW) { this.#recentlyAnsweredQueries.delete(key); } } // Build query signature; names lower-cased per RFC 6762 §16. const queryKey = queries .map(q => `${q.name.toLowerCase()}-${q.recordType}`) .sort() .join("|") + `-${sourceIntf}`; const cached = this.#recentlyAnsweredQueries.get(queryKey); if (cached && now - cached.timestamp < QUESTION_SUPPRESSION_WINDOW) { // Check if all our answers are already in the known answers from the cached response const answerHashes = answers.map(a => this.buildDnsRecordKey(a, sourceIntf)); const allAnswersKnown = answerHashes.every(h => cached.knownAnswerHashes.has(h)); if (allAnswersKnown) { return true; // Suppress - another responder already answered with our records } } // Record that we're answering this question const knownAnswerHashes = new Set(); for (const answer of knownAnswers) { knownAnswerHashes.add(this.buildDnsRecordKey(answer, sourceIntf)); } // Also add our answers to the known set for (const answer of answers) { knownAnswerHashes.add(this.buildDnsRecordKey(answer, sourceIntf)); } this.#recentlyAnsweredQueries.set(queryKey, { knownAnswerHashes, timestamp: now, }); return false; } async #processTruncatedQuery(key: string) { const { message, timer } = this.#truncatedQueryCache.get(key) ?? {}; this.#truncatedQueryCache.delete(key); timer?.stop(); if (message) { if (message.queries.length === 0) { // Should not happen but ignore if it does return; } message.messageType &= ~DnsMessageTypeFlag.TC; // Clear TC flag await this.#handleMessage(message); } } /** * Delays processing of truncated messages to allow combining multiple parts or combines them if possible */ #prepareMessage(newMessage: MdnsSocket.Message): MdnsSocket.Message | undefined { const { messageType, transactionId, sourceIntf, sourceIp } = newMessage; if (!DnsMessageType.isQuery(messageType)) { // We are only interested in queries return; } const key = `${transactionId}-${sourceIntf}-${sourceIp}`; const { message: existingMessage, timer } = this.#truncatedQueryCache.get(key) ?? {}; this.#truncatedQueryCache.delete(key); timer?.stop(); const message = existingMessage ? { ...existingMessage, queries: [...existingMessage.queries, ...newMessage.queries], answers: [...existingMessage.answers, ...newMessage.answers], additionalRecords: [...existingMessage.additionalRecords, ...newMessage.additionalRecords], messageType: newMessage.messageType, // Keep TC flag as is from the latest message } : newMessage; // Message was not truncated, or we have now received all details, process it if ((messageType & DnsMessageTypeFlag.TC) === 0) { if (message.queries.length === 0) { // Should not happen but ignore if it does return; } return message; } // We have stored a new or updated truncated message - store and wait for next part // Delay should be max 400-500ms as per RFC 6762 section 7.2 this.#truncatedQueryCache.set(key, { message, timer: Time.getTimer(`Truncated MDNS message ${key}`, Millis(400 + Math.floor(Math.random() * 100)), () => this.#processTruncatedQuery(key), ).start(), }); } } export namespace MdnsServer { export interface RecordGenerator { (intf: string, addrs: NetworkInterfaceDetails, hostname: string): DnsRecord[]; } export interface InterfaceRecords { byService: Map[]>; /** Lower-cased names of records we own on this interface - used to fast-reject unrelated LAN queries. */ ownedNames: Set; } } function hostnameForMac(mac: string) { return `${mac.replace(/:/g, "").toUpperCase()}0000.local`; } /** * Prepares records for the wire, clearing the cache-flush bit wherever we cannot honor what it claims. * * The bit says the receiver may drop everything else it holds for the name and type, which is only true if this * response carries that whole set — suppression and rate limiting both remove records before we get here. A legacy * resolver, which we cannot distinguish because the source port does not reach us, must never see the bit at all, so * a unicast response omits it. * * @see {@link https://www.rfc-editor.org/rfc/rfc6762#section-10.2} RFC 6762 §10.2 * @see {@link https://www.rfc-editor.org/rfc/rfc6762#section-6.7} RFC 6762 §6.7 */ function sendable(sent: DnsRecord[], complete: DnsRecord[], isUnicast: boolean) { if (isUnicast) { return sent.map(record => (record.flushCache ? { ...record, flushCache: false } : record)); } if (!sent.some(record => record.flushCache)) { return sent; } const sentSizes = setSizes(sent); const completeSizes = setSizes(complete); return sent.map(record => record.flushCache && (sentSizes.get(setKeyOf(record)) ?? 0) < (completeSizes.get(setKeyOf(record)) ?? 0) ? { ...record, flushCache: false } : record, ); } /** Identifies the record set a record belongs to: RFC 6762 scopes the cache-flush bit to one name, type and class. */ function setKeyOf(record: DnsRecord) { return `${record.recordType}-${record.recordClass}-${record.name.toLowerCase()}`; } function setSizes(records: DnsRecord[]) { const sizes = new Map(); for (const record of records) { const key = setKeyOf(record); sizes.set(key, (sizes.get(key) ?? 0) + 1); } return sizes; } /** DNS names are case-insensitive (RFC 6762 §16), but they rarely differ in case, so try the cheap comparison first. */ function sameName(a: string, b: string) { return a === b || a.toLowerCase() === b.toLowerCase(); }