Skip to content

🎧 Your Personal Streaming Service

feat(jellyfin): add System/Endpoint so Finamp's connection test passes (#5955)

Deluan Quintãoaa0824e03bfd
diff --git a/server/jellyfin/README.md b/server/jellyfin/README.md
index 195173c2a..5759e6cc0 100644
--- a/server/jellyfin/README.md
+++ b/server/jellyfin/README.md
@@ -112,7 +112,7 @@ returns direct children only (no tracks — no track is a library's direct child
| Area | Endpoints |
|---|---|
-| Handshake / system | `GET System/Info/Public`, `GET System/Info` (authenticated), `GET`/`POST System/Ping`, `GET QuickConnect/Enabled` |
+| Handshake / system | `GET System/Info/Public`, `GET System/Info` (authenticated), `GET`/`POST System/Ping`, `GET System/Endpoint` (authenticated), `GET QuickConnect/Enabled` |
| Auth | `POST Users/AuthenticateByName`, `GET Users/Public` |
| Users | `GET UserViews`, `GET Users/{userId}/Views`, `GET Users/Me`, `GET Users/{userId}` |
| Browsing | `GET Items`, `GET Users/{userId}/Items`, `GET Items/{itemId}`, `GET Users/{userId}/Items/{itemId}`, `GET Users/{userId}/Items/Latest`, `DELETE Items/{itemId}` (playlists only) |
diff --git a/server/jellyfin/api.go b/server/jellyfin/api.go
index 8a175df35..d64366a63 100644
--- a/server/jellyfin/api.go
+++ b/server/jellyfin/api.go
@@ -104,6 +104,7 @@ func (api *Router) routes() http.Handler {
// player) even before the first playback report.
r.Use(api.withPlayer)
r.Get("/system/info", api.getSystemInfo)
+ r.Get("/system/endpoint", api.getEndpointInfo)
r.Get("/userviews", api.getUserViews)
r.Get("/users/{userId}/views", api.getUserViews)
r.Get("/users/me", api.getCurrentUser)
diff --git a/server/jellyfin/dto/dto.go b/server/jellyfin/dto/dto.go
index 5a2a4c2b1..58a6b919e 100644
--- a/server/jellyfin/dto/dto.go
+++ b/server/jellyfin/dto/dto.go
@@ -20,6 +20,12 @@ type SystemInfo struct {
CachePath string `json:"CachePath,omitempty"`
}
+// EndPointInfo describes the caller's network location (GET /System/Endpoint).
+type EndPointInfo struct {
+ IsLocal bool `json:"IsLocal"`
+ IsInNetwork bool `json:"IsInNetwork"`
+}
+
type NameGuidPair struct {
Name string `json:"Name"`
Id string `json:"Id"`
diff --git a/server/jellyfin/e2e/system_test.go b/server/jellyfin/e2e/system_test.go
index c6f9145d5..ac8c350c4 100644
--- a/server/jellyfin/e2e/system_test.go
+++ b/server/jellyfin/e2e/system_test.go
@@ -51,6 +51,22 @@ var _ = Describe("System", func() {
})
})
+ Describe("GET /System/Endpoint", func() {
+ It("always reports IsInNetwork, which Finamp's connection test probes for", func() {
+ w := getAs(regularUser, "/System/Endpoint")
+ Expect(w.Code).To(Equal(http.StatusOK))
+ var info map[string]any
+ parseInto(w, &info)
+ Expect(info).To(HaveKey("IsInNetwork"))
+ Expect(info).To(HaveKey("IsLocal"))
+ })
+
+ It("rejects unauthenticated requests", func() {
+ w := rawReq("GET", "/System/Endpoint", "")
+ Expect(w.Code).To(Equal(http.StatusUnauthorized))
+ })
+ })
+
Describe("GET/POST /System/Ping", func() {
It("answers GET with a plain-text server name", func() {
w := rawReq("GET", "/System/Ping", "")
diff --git a/server/jellyfin/system.go b/server/jellyfin/system.go
index ea553fd87..8b847987f 100644
--- a/server/jellyfin/system.go
+++ b/server/jellyfin/system.go
@@ -5,7 +5,9 @@ import (
"encoding/hex"
"errors"
"fmt"
+ "net"
"net/http"
+ "net/netip"
"path"
"strings"
@@ -108,6 +110,48 @@ func (api *Router) ping(w http.ResponseWriter, r *http.Request) {
_, _ = w.Write([]byte(api.serverName()))
}
+// getEndpointInfo answers /System/Endpoint, which Finamp's connection test uses to pick between a
+// dual-connection setup's addresses; a missing IsInNetwork reads to it as "not a Jellyfin server".
+func (api *Router) getEndpointInfo(w http.ResponseWriter, r *http.Request) {
+ remote := remoteIP(r)
+ api.ok(w, r, dto.EndPointInfo{
+ IsLocal: isSameMachine(r, remote),
+ IsInNetwork: isInLocalNetwork(remote),
+ })
+}
+
+// isInLocalNetwork mirrors Jellyfin's default LAN set (NetworkManager.UpdateSettings with no
+// LocalNetworkSubnets configured): loopback, the RFC 1918 ranges, fc00::/7 and fe80::/10.
+func isInLocalNetwork(ip netip.Addr) bool {
+ return ip.IsLoopback() || ip.IsPrivate() || (ip.Is6() && ip.IsLinkLocalUnicast())
+}
+
+// isSameMachine mirrors Jellyfin's HttpContext.IsLocal(): the caller shares the connection's local
+// address. The local address is missing in tests and unreliable behind a proxy, so fall back to loopback.
+func isSameMachine(r *http.Request, remote netip.Addr) bool {
+ local, ok := r.Context().Value(http.LocalAddrContextKey).(net.Addr)
+ if !ok {
+ return remote.IsLoopback()
+ }
+ return parseIP(local.String()) == remote
+}
+
+// remoteIP parses RemoteAddr, which the RealIP middleware may have rewritten to a bare IP.
+func remoteIP(r *http.Request) netip.Addr {
+ return parseIP(r.RemoteAddr)
+}
+
+func parseIP(addr string) netip.Addr {
+ if h, _, err := net.SplitHostPort(addr); err == nil {
+ addr = h
+ }
+ ip, err := netip.ParseAddr(addr)
+ if err != nil {
+ return netip.Addr{}
+ }
+ return ip.Unmap()
+}
+
func (api *Router) quickConnectEnabled(w http.ResponseWriter, r *http.Request) {
api.ok(w, r, false)
}
diff --git a/server/jellyfin/system_test.go b/server/jellyfin/system_test.go
index a7f7df6a4..4b3ac240e 100644
--- a/server/jellyfin/system_test.go
+++ b/server/jellyfin/system_test.go
@@ -4,6 +4,7 @@ import (
"context"
"encoding/json"
"errors"
+ "net"
"net/http"
"net/http/httptest"
@@ -88,6 +89,61 @@ var _ = Describe("System", func() {
Expect(w.Body.String()).To(HavePrefix("Navidrome"))
})
+ DescribeTable("reports the caller's network location on /System/Endpoint",
+ func(remoteAddr string, isLocal, isInNetwork bool) {
+ w := httptest.NewRecorder()
+ r := httptest.NewRequest("GET", "/System/Endpoint", nil)
+ r.RemoteAddr = remoteAddr
+ api.getEndpointInfo(w, r)
+
+ Expect(w.Code).To(Equal(http.StatusOK))
+ // Finamp's connection test only probes for the key's presence, so it must always be emitted.
+ Expect(w.Body.String()).To(ContainSubstring(`"IsInNetwork"`))
+ var info dto.EndPointInfo
+ Expect(json.Unmarshal(w.Body.Bytes(), &info)).To(Succeed())
+ Expect(info.IsLocal).To(Equal(isLocal))
+ Expect(info.IsInNetwork).To(Equal(isInNetwork))
+ },
+ Entry("loopback", "127.0.0.1:12345", true, true),
+ Entry("IPv6 loopback", "[::1]:12345", true, true),
+ Entry("LAN address", "192.168.1.20:54321", false, true),
+ Entry("bare IP, as left by the RealIP middleware", "10.0.0.5", false, true),
+ Entry("IPv4-mapped IPv6 LAN address", "[::ffff:172.16.0.9]:80", false, true),
+ Entry("IPv6 link-local", "[fe80::1]:80", false, true),
+ Entry("IPv6 unique-local", "[fd00::1]:80", false, true),
+ // Jellyfin's default LAN set omits 169.254.0.0/16, so we do too.
+ Entry("IPv4 link-local", "169.254.1.1:80", false, false),
+ Entry("public address", "8.8.8.8:443", false, false),
+ Entry("unparseable address", "not-an-ip", false, false),
+ )
+
+ It("reports IsLocal when the caller shares the connection's local address", func() {
+ w := httptest.NewRecorder()
+ r := httptest.NewRequest("GET", "/System/Endpoint", nil)
+ r.RemoteAddr = "192.168.1.20:54321"
+ ctx := context.WithValue(r.Context(), http.LocalAddrContextKey,
+ &net.TCPAddr{IP: net.ParseIP("192.168.1.20"), Port: 4533})
+ api.getEndpointInfo(w, r.WithContext(ctx))
+
+ var info dto.EndPointInfo
+ Expect(json.Unmarshal(w.Body.Bytes(), &info)).To(Succeed())
+ Expect(info.IsLocal).To(BeTrue())
+ })
+
+ It("does not report IsLocal for a different host on the same LAN", func() {
+ w := httptest.NewRecorder()
+ r := httptest.NewRequest("GET", "/System/Endpoint", nil)
+ r.RemoteAddr = "192.168.1.99:54321"
+ ctx := context.WithValue(r.Context(), http.LocalAddrContextKey,
+ &net.TCPAddr{IP: net.ParseIP("192.168.1.20"), Port: 4533})
+ api.getEndpointInfo(w, r.WithContext(ctx))
+
+ var info dto.EndPointInfo
+ Expect(json.Unmarshal(w.Body.Bytes(), &info)).To(Succeed())
+ Expect(info.IsLocal).To(BeFalse())
+ Expect(info.IsInNetwork).To(BeTrue())
+ })
+
It("reports quick connect as disabled", func() {
w := httptest.NewRecorder()
r := httptest.NewRequest("GET", "/QuickConnect/Enabled", nil)