feat(discovery): native-protocol LAN auto-discovery over mDNS

Both the unified host (serve --native) and standalone m3-host now advertise the
native punktfunk/1 service over mDNS (_punktfunk._udp) — the analogue of the
GameStream _nvstream._tcp advert. TXT records carry proto, the host cert
fingerprint (fp, the value clients pin), the pairing requirement
(pair=required|optional), and the host id. New crate::discovery module, wired
into m3::serve so both host entry points get it; best-effort, never blocks
streaming (--connect always works).

Client gains `punktfunk-client-rs --discover [SECS]`: browses the LAN and prints
each host (name, addr:port, pairing, fingerprint), then exits. Apple clients
browse the same service natively via NWBrowser (service type + TXT keys are the
contract).

Validated cross-LAN: the dev box discovered the GNOME-box appliance
(pair=required) and a standalone synthetic host (pair=optional); fingerprint and
pairing state correct in both.

Also refresh the now-stale sendmmsg caveat in the bitrate doc (batched/paced send
landed + validated to 1 Gbps) and mark the encode|send thread split done in §12.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

crates/punktfunk-host/src/discovery.rs

@@ -0,0 +1,65 @@
+//! mDNS advertisement of the native punktfunk/1 service so native clients auto-discover the
+//! host — the native-protocol analogue of the GameStream `_nvstream._tcp` advert
+//! ([`crate::gamestream::mdns`]).
+//!
+//! The service type is **`_punktfunk._udp.local.`** (UDP because punktfunk/1 is QUIC, and the
+//! advertised port is the QUIC control/data port a client `--connect`s). TXT records carry:
+//! - `proto` — the wire protocol id ([`NATIVE_PROTO`]), so a future incompatible revision is
+//!   distinguishable by discovery alone;
+//! - `fp` — the host certificate SHA-256 (lowercase hex), the exact value a client pins. mDNS is
+//!   unauthenticated, so this is advisory — TOFU/pinning still verifies it on connect — but it
+//!   lets a picker show the fingerprint and pre-pin a chosen host;
+//! - `pair` — `required` or `optional`, so a client can tell up front whether it must run the PIN
+//!   pairing ceremony before it can stream;
+//! - `id` — the stable host uniqueid (dedup across IPs / re-advertises).
+
+use anyhow::{Context, Result};
+use mdns_sd::{ServiceDaemon, ServiceInfo};
+use std::collections::HashMap;
+use std::net::IpAddr;
+
+/// The native-protocol mDNS service type. Clients browse this to find punktfunk/1 hosts.
+pub const NATIVE_SERVICE: &str = "_punktfunk._udp.local.";
+
+/// Wire protocol id advertised in the `proto` TXT record.
+pub const NATIVE_PROTO: &str = "punktfunk/1";
+
+/// Holds the mDNS daemon; dropping it unregisters the service.
+pub struct Advert {
+    _daemon: ServiceDaemon,
+}
+
+/// Advertise the native host on the LAN. `fingerprint` is the host cert SHA-256 (lowercase hex);
+/// `require_pairing` tells a discovering client whether it must pair before it can stream.
+pub fn advertise_native(
+    hostname: &str,
+    ip: IpAddr,
+    port: u16,
+    fingerprint: &str,
+    require_pairing: bool,
+    uniqueid: &str,
+) -> Result<Advert> {
+    let daemon = ServiceDaemon::new().context("create mDNS daemon")?;
+    let host_name = format!("{hostname}.local.");
+    let mut props: HashMap<String, String> = HashMap::new();
+    props.insert("proto".into(), NATIVE_PROTO.into());
+    props.insert("fp".into(), fingerprint.to_string());
+    props.insert(
+        "pair".into(),
+        if require_pairing { "required" } else { "optional" }.into(),
+    );
+    props.insert("id".into(), uniqueid.to_string());
+    let service = ServiceInfo::new(NATIVE_SERVICE, hostname, &host_name, ip, port, props)
+        .context("build native mDNS ServiceInfo")?;
+    daemon
+        .register(service)
+        .context("register native mDNS service")?;
+    tracing::info!(
+        service = "_punktfunk._udp",
+        port,
+        host = %host_name,
+        pair = if require_pairing { "required" } else { "optional" },
+        "native punktfunk/1 mDNS advertising"
+    );
+    Ok(Advert { _daemon: daemon })
+}

crates/punktfunk-host/src/m3.rs

@@ -159,6 +159,27 @@ pub(crate) async fn serve(opts: M3Options, np: Arc<NativePairing>) -> Result<()>
         "punktfunk/1 host listening (QUIC) — clients pin this fingerprint"
     );
 
+    // mDNS: advertise the native service so clients auto-discover this host (the analogue of the
+    // GameStream _nvstream advert; both run in the unified host). Held for the host's lifetime —
+    // dropping `_advert` unregisters. Best-effort: a discovery failure must not stop streaming
+    // (manual `--connect HOST:PORT` always works), so we log and continue.
+    let _advert = match crate::gamestream::Host::detect() {
+        Ok(h) => crate::discovery::advertise_native(
+            &h.hostname,
+            h.local_ip,
+            opts.port,
+            &fingerprint_hex(&fingerprint),
+            opts.require_pairing,
+            &h.uniqueid,
+        )
+        .map_err(|e| tracing::warn!(error = %format!("{e:#}"), "native mDNS advertise failed (continuing)"))
+        .ok(),
+        Err(e) => {
+            tracing::warn!(error = %format!("{e:#}"), "host detect for mDNS failed (continuing)");
+            None
+        }
+    };
+
     // One audio capturer for the whole host lifetime, handed from session to session
     // (avoids a PipeWire stream setup per session — see AudioCapSlot).
     let audio_cap: AudioCapSlot = Arc::new(std::sync::Mutex::new(None));
@@ -236,10 +257,10 @@ const DEFAULT_BITRATE_KBPS: u32 = 20_000;
 /// above unusable, and a **2 Gbps** ceiling is generous headroom over the 1 Gbps+ target that
 /// GF(2¹⁶) Leopard FEC was built to reach — it lifts the GF(2⁸)/~1 Gbps wall, and at 1 Gbps a frame
 /// is only a few-hundred shards in one block (far under the 65535 limit). Enough for 5K@240 with
-/// margin. Resolved value is echoed in `Welcome::bitrate_kbps`. CAVEAT: the native data plane still
-/// does one `send()` syscall per packet (no `sendmmsg` batching / paced send thread yet), so
-/// sustained multi-hundred-Mbps can show send-buffer drops (counted as `packets_send_dropped`)
-/// until that lands — see the 1 Gbps work in the roadmap.
+/// margin. Resolved value is echoed in `Welcome::bitrate_kbps`. The native data plane batches sends
+/// (`sendmmsg`) and paces each frame on a dedicated send thread (microburst cap), validated to a
+/// clean 1 Gbps with zero send-buffer drops; sustained overruns are still counted as
+/// `packets_send_dropped`.
 const MIN_BITRATE_KBPS: u32 = 500;
 const MAX_BITRATE_KBPS: u32 = 2_000_000;
 

crates/punktfunk-host/src/main.rs

@@ -15,6 +15,7 @@
 
 mod audio;
 mod capture;
+mod discovery;
 mod encode;
 mod gamestream;
 mod inject;
@@ -437,6 +438,8 @@ NOTES:
     'portal' needs headless Sway + xdg-desktop-portal-wlr running in this session
     (see docs/linux-setup.md). 'synthetic' needs no capture session and always runs.
     Encoded AUs are written to a playable file AND (unless --no-loopback) fed through a
-    punktfunk_core host→client loopback that reassembles and byte-verifies each one."
+    punktfunk_core host→client loopback that reassembles and byte-verifies each one.
+    Both 'serve --native' and 'm3-host' advertise the native service over mDNS
+    (_punktfunk._udp) for client auto-discovery — 'punktfunk-client-rs --discover' lists them."
     );
 }