From bae8742e488103e0ab29fdaa6739af1a762a2746 Mon Sep 17 00:00:00 2001 From: enricobuehler Date: Thu, 6 Aug 2026 01:56:42 +0200 Subject: [PATCH] fix(apple): the library's unreachable message pointed at the wrong layer It led with `--mgmt-bind 127.0.0.1`, a rare cause, and never mentioned the one fact that actually explains the symptom: the library rides the management API on a different port (47990) than the QUIC stream plane (9777), so it can fail while streaming to the same host works. Field triage of exactly that case spent hours on the stream path before anyone questioned the port. Leads with that now, and names browser-testing the port as the fast split between "unreachable" and anything client-side. --- .../PunktfunkKit/Connection/LibraryClient.swift | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/clients/apple/Sources/PunktfunkKit/Connection/LibraryClient.swift b/clients/apple/Sources/PunktfunkKit/Connection/LibraryClient.swift index b7024989..e8460fcf 100644 --- a/clients/apple/Sources/PunktfunkKit/Connection/LibraryClient.swift +++ b/clients/apple/Sources/PunktfunkKit/Connection/LibraryClient.swift @@ -94,9 +94,16 @@ public enum LibraryError: LocalizedError { case .http(let code): return "The management API returned HTTP \(code)." case .unreachable(let why): - return "Couldn't reach the host's management API: \(why). It binds the LAN by default, " - + "so check the host is updated and reachable (a host pinned to " - + "`--mgmt-bind 127.0.0.1` is loopback-only and can't be browsed remotely)." + // The library rides a DIFFERENT port than the stream (the management API, 47990 by + // default; the stream is QUIC on 9777), so it can fail while streaming to the same + // host works perfectly — say that first, because the opposite assumption has sent + // more than one person hunting the wrong layer. Opening that URL in a browser is the + // fastest way to tell "port unreachable" apart from anything client-side. + return "Couldn't reach the host's management API: \(why). The library uses a " + + "different port than the stream (47990 by default), so streaming can work " + + "while this doesn't. Check that port is reachable from this device, and that " + + "the host isn't pinned to `--mgmt-bind 127.0.0.1`, which serves it to the " + + "host itself only." } } }