swift-mDNS

A pure Swift implementation of Multicast DNS (mDNS, RFC 6762) and DNS Service Discovery (DNS-SD, RFC 6763). Embedded-first: the wire codec is Foundation-free and the byte currency is [UInt8] / MDNSService / P2PCore.IPAddress; no Data / ByteBuffer / NIO type appears on the public surface.

Release status. The released 1.2.0 ships the prior API. The Embedded-first API documented here lives on the unreleased embedded branch (M8 pending) and is not tagged — pin to the branch to use it.

Features

Pure Swift — no C dependencies; the DNSWire codec works on all Swift platforms.
RFC compliant — RFC 1035 (DNS), RFC 6762 (mDNS), RFC 6763 (DNS-SD), RFC 2782 (SRV).
Embedded-first — [UInt8] byte currency; the DNSWire codec has no Foundation / NIO / any.
Modern concurrency — actors and Sendable types; typed-throws discovery stream.
Hardened parsing — wire decoding strictly bounds-checks hostile input and throws DNSError on malformed data instead of trapping; compression-pointer jumps are capped; the message decoder enforces a size ceiling and caps speculative reservations; unknown opcode / rcode / class / record-type values are preserved (.unknown) rather than silently defaulted.

Requirements

Swift 6.2+
macOS 26+ / iOS 18+ / tvOS 18+ / watchOS 11+ / visionOS 2+ (the Embedded-first baseline; the facade surfaces P2PCore.IPAddress, whose package floors at macOS 26)

Installation

Add swift-mDNS to your Package.swift. While the Embedded API is on the unreleased embedded branch, depend on the branch:

dependencies: [
    .package(url: "https://github.com/1amageek/swift-mDNS.git", branch: "embedded")
]

Then add the product(s) you need to your target dependencies:

.target(
    name: "YourTarget",
    dependencies: ["MDNS"]          // and/or "DNSWire" for the raw codec
)

Quick Start

Service browsing

import MDNS

let browser = MDNSBrowser()

// Iteration yields MDNSService and throws MDNSError. An updated/removed service
// arrives as a fresh value; deduplicate on service.id.
for try await service in try await browser.browse("_http._tcp.local.") {
    print("Found: \(service.name) at \(service.host ?? "unknown"):\(service.port ?? 0)")
}

Service advertising

import MDNS

let responder = MDNSResponder()

let service = MDNSService(
    name: "My Web Server",
    type: "_http._tcp",
    port: 8080,
    txt: ["path": Array("/api".utf8), "version": Array("1.0".utf8)]
)

try await responder.advertise(service)

// Later, to withdraw (sends a goodbye, TTL == 0):
try await responder.withdraw(service)
await responder.stop()

Low-level DNS message handling (Tier-3)

import DNSWire

let query = try DNSMessage.mdnsQuery(for: "_http._tcp.local.")
let encoded: [UInt8] = query.encode()

let message = try DNSMessage.decode(from: receivedBytes)
for answer in message.answers {
    switch answer.rdata {
    case .ptr(let serviceName): print("PTR -> \(serviceName)")
    case .srv(let srv):         print("SRV -> \(srv.target):\(srv.port)")
    case .txt(let strings):     print("TXT -> \(strings)")
    case .a(let addr):          print("A -> \(addr)")
    case .aaaa(let addr):       print("AAAA -> \(addr)")
    default:                    break
    }
}

Products

This package ships two products following the Embedded-first 3-tier API design.

Product	Tier	Import	Use it for
`MDNS`	Tier-1 facade	`import MDNS`	Browse / advertise services. `[UInt8]` / `MDNSService` / `IPAddress` currency.
`DNSWire`	Tier-3 codec	`import DNSWire`	The Foundation-free DNS/mDNS wire codec. Not pulled in by `import MDNS`.

Architecture

Three layers, top to bottom:

┌─────────────────────────────────────────────────────────────┐
│  Tier-1 facade  (import MDNS)                                │
│  MDNSBrowser (actor), MDNSResponder (actor)                  │
│  MDNSService (value), MDNSError, MDNSDiscoveries            │
│  Currency: [UInt8] / MDNSService / P2PCore.IPAddress        │
├─────────────────────────────────────────────────────────────┤
│  MDNSTransport (package protocol) + NIODNSTransport         │
│  - mDNS-specific abstraction over UDP                       │
│  - the only place [UInt8] <-> ByteBuffer crosses the edge   │
│  - joins mDNS multicast groups (224.0.0.251, ff02::fb)      │
│  - built on NIOUDPTransport from swift-nio-udp              │
├─────────────────────────────────────────────────────────────┤
│  Tier-3 codec  (import DNSWire)                             │
│  DNSMessage, DNSName, DNSResourceRecord, DNSRecordData,     │
│  IPv4Address, IPv6Address, DNSError, WriteBuffer            │
│  - Embedded-clean: no Foundation, no NIO, no `any`          │
└─────────────────────────────────────────────────────────────┘

MDNSService is a Foundation-free DNS-SD service instance: addresses are P2PCore.IPAddress, txt values are raw [UInt8] (no String-valued TXT API). id is the full service name, so consumers deduplicate discoveries by id.
MDNSDiscoveries is the named typed sequence the browser vends: AsyncSequence<MDNSService, MDNSError>. There is no .found / .updated / .removed event enum — an updated or removed service is delivered as a fresh value, and a goodbye (TTL == 0) re-emits the last-known state.
MDNSBrowser sends PTR queries and, when autoResolve is on, issues SRV/TXT follow-ups to resolve found instances. Calling browse(_:) more than once adds another service type to the same discovery stream.
MDNSResponder answers queries for registered services and announces with backoff; withdraw(_:) / stop() send goodbye messages (TTL == 0).
MDNSTransport is a package protocol (the test / adapter injection seam); NIODNSTransport is the production implementation, the single place where [UInt8] crosses to / from a NIO ByteBuffer.

DNSWire carries no swift-p2p-core dependency, which keeps it off the macOS-26 Span platform requirement of P2PCore and lets swift build --target DNSWire compile under Embedded Swift. The package's single platform set still adopts the shared Embedded-first baseline (macOS 26) because the MDNS facade surfaces P2PCore.IPAddress. See Sources/MDNS/CONTEXT.md for the load-bearing invariants.

Security

The DNSWire decoder rejects hostile input rather than trapping or silently substituting defaults:

strict bounds checks on all RDATA (including NSEC) and DNS names;
decode-time RFC 1035 name-length enforcement (255-byte cap, applied incrementally);
compression-pointer loop / forward-reference detection (jumps capped at 128, every pointer must point strictly backward and within bounds);
a hard DNSMessage size ceiling enforced before any attacker-controlled section count is read, plus capped speculative reservations (min(count, remainingBytes / minEntrySize)) against forged 0xFFFF section counts;
strict UTF-8 in TXT/HINFO labels (malformed input throws DNSError);
preservation of unrecognized opcode/rcode/class/record-type values as .unknown(...).

Inbound multicast datagrams that fail to decode are dropped per RFC 6762 (the receive loop is never torn down) but are counted (droppedDecodeFailureCount) and surfaced via a throttled log, so persistent malformed traffic stays detectable.

RFC Compliance

RFC	Title	Coverage
RFC 1035	Domain Names	Message format, name encoding/decoding, compression
RFC 6762	Multicast DNS	Multicast addressing/port, cache-flush bit, QU bit, goodbye (TTL 0)
RFC 6763	DNS-Based Service Discovery	PTR/SRV/TXT service-discovery flow
RFC 2782	DNS SRV Records	SRV target/port/priority/weight

Performance

The DNSWire codec is optimized for throughput with minimal allocations: index-based parsing over raw byte arrays, inline (stack-allocated) IPv4/IPv6 storage, DNS name compression, a ContiguousArray-backed write buffer, and ~Copyable buffers. The host NIO adapter performs one bulk copy at the [UInt8] / ByteBuffer boundary.

Measured on Apple Silicon (M-series):

Operation	Throughput	Latency
IPv4Address creation	202M ops/sec	5 ns
IPv6Address creation	479M ops/sec	2 ns
DNSName decoding	3.2M ops/sec	0.31 μs
DNSName encoding	230K ops/sec	4.3 μs
DNSMessage query decoding	1.15M ops/sec	0.87 μs
DNSMessage query encoding	202K ops/sec	5.0 μs
DNSMessage response decoding	300K ops/sec	3.3 μs
End-to-end roundtrip	170K ops/sec	5.9 μs

Run the benchmarks:

swift test --filter Benchmark

Testing

The mDNSTests target covers both the Tier-3 codec (DNSWire) and the Tier-1 facade (MDNS). Run with a timeout to guard against hangs:

swift test

References

RFC 1035 — Domain Names — Implementation and Specification
RFC 6762 — Multicast DNS
RFC 6763 — DNS-Based Service Discovery
RFC 2782 — DNS SRV Records

License

MIT License

swift-mDNS

1.2.2

What's New

1.2.2

2026-06-26T13:35:20Z

swift-mDNS

Features

Requirements

Installation

Quick Start

Service browsing

Service advertising

Low-level DNS message handling (Tier-3)

Products

Architecture

Security

RFC Compliance

Performance

Testing

References

License

Description

Dependencies