Reply OfflinePong immediately so offline remotes stay on LAN.

Synchronous recovery probes delayed the offline advertisement past console
discovery timeouts on blackholed hosts; probe health in the background instead.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: jhead

internal/proto/proto.go

@@ -59,7 +59,8 @@ var OfflinePong = UnconnectedPing{
 		ProtocolVersion: "390",
 		Version:         "1.14.60",
 		Players:         "0",
-		MaxPlayers:      "0",
+		// Non-zero capacity: some consoles omit full/zero-slot entries from Friends.
+		MaxPlayers:      "1",
 		GameType:        "Creative",
 		NintendoLimited: "1",
 		// Placeholder ports so rewriteUnconnectedPong overwrites them with

internal/proxy/discovery_ping_test.go

@@ -130,3 +130,62 @@ func TestBuildOfflinePongEchoesPingTime(t *testing.T) {
 	require.Equal(t, proto.UnconnectedPongID, pong[0])
 	require.True(t, bytes.Equal(pong[1:9], pingTime[:]))
 }
+
+// TestOfflineDiscoveryPingRepliesImmediately guards the LAN-list bug where
+// phantom waited on a recovery probe before sending OfflinePong. Blackholed
+// remotes take the full deadline, so consoles timed out and never showed the
+// offline entry even though a pong was eventually sent.
+func TestOfflineDiscoveryPingRepliesImmediately(t *testing.T) {
+	blackhole, err := net.ListenUDP("udp", &net.UDPAddr{IP: net.IPv4(127, 0, 0, 1), Port: 0})
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = blackhole.Close() })
+
+	proxyServer, err := New(ProxyPrefs{
+		BindAddress:              "127.0.0.1",
+		BindPort:                 0,
+		RemoteServer:             blackhole.LocalAddr().String(),
+		IdleTimeout:              time.Minute,
+		NumWorkers:               1,
+		DisableDiscoveryListener: true,
+	})
+	require.NoError(t, err)
+
+	dataConn, err := net.ListenUDP("udp", proxyServer.bindAddress)
+	require.NoError(t, err)
+	proxyServer.server.Store(dataConn)
+	t.Cleanup(func() {
+		proxyServer.dead.Set()
+		_ = dataConn.Close()
+		proxyServer.clientMap.Close()
+	})
+
+	// If handleDiscoveryPing waited for recovery, this would delay the reply.
+	prev := discoveryRecoveryProbeTimeoutNanos.Swap(int64(2 * time.Second))
+	t.Cleanup(func() { discoveryRecoveryProbeTimeoutNanos.Store(prev) })
+
+	proxyServer.markServerOffline()
+
+	clientConn, err := net.ListenUDP("udp", &net.UDPAddr{IP: net.IPv4(127, 0, 0, 1), Port: 0})
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = clientConn.Close() })
+	clientAddr := clientConn.LocalAddr().(*net.UDPAddr)
+
+	pingTime := [8]byte{9, 8, 7, 6, 5, 4, 3, 2}
+	started := time.Now()
+	require.NoError(t, proxyServer.handleDiscoveryPing(clientAddr, bareUnconnectedPing(pingTime)))
+	elapsed := time.Since(started)
+	if elapsed >= 200*time.Millisecond {
+		t.Fatalf("offline pong took %v; must not wait on upstream recovery probe", elapsed)
+	}
+
+	_ = clientConn.SetReadDeadline(time.Now().Add(time.Second))
+	buf := make([]byte, 2048)
+	n, _, err := clientConn.ReadFromUDP(buf)
+	require.NoError(t, err)
+	require.Equal(t, proto.UnconnectedPongID, buf[0])
+	require.True(t, bytes.Equal(buf[1:9], pingTime[:]), "pong must echo ping time")
+
+	packet, err := proto.ReadUnconnectedPing(buf[:n])
+	require.NoError(t, err)
+	require.Contains(t, packet.Pong.MOTD, "offline")
+}

internal/proxy/discovery_test.go

@@ -18,6 +18,9 @@ func TestHandleUnconnectedPingOfflineReply(t *testing.T) {
 	defer client.Close()
 
 	// Closed port: discovery probe fails quickly and offline pong is advertised.
+	prev := discoveryPingTimeoutNanos.Swap(int64(200 * time.Millisecond))
+	t.Cleanup(func() { discoveryPingTimeoutNanos.Store(prev) })
+
 	p, err := New(ProxyPrefs{
 		BindAddress:              "127.0.0.1",
 		BindPort:                 0,
@@ -34,10 +37,6 @@ func TestHandleUnconnectedPingOfflineReply(t *testing.T) {
 	}
 	defer p.Close()
 
-	prev := discoveryPingTimeout
-	discoveryPingTimeout = 200 * time.Millisecond
-	defer func() { discoveryPingTimeout = prev }()
-
 	ping := []byte{proto.UnconnectedPingID, 1, 2, 3, 4, 5, 6, 7, 8}
 	if err := p.HandleUnconnectedPing(ping, client.LocalAddr()); err != nil {
 		t.Fatalf("HandleUnconnectedPing: %v", err)
@@ -71,6 +70,9 @@ func TestHandleUnconnectedPingOpenConnections(t *testing.T) {
 	}
 	defer client.Close()
 
+	prev := discoveryPingTimeoutNanos.Swap(int64(200 * time.Millisecond))
+	t.Cleanup(func() { discoveryPingTimeoutNanos.Store(prev) })
+
 	p, err := New(ProxyPrefs{
 		BindAddress:              "127.0.0.1",
 		BindPort:                 0,
@@ -87,10 +89,6 @@ func TestHandleUnconnectedPingOpenConnections(t *testing.T) {
 	}
 	defer p.Close()
 
-	prev := discoveryPingTimeout
-	discoveryPingTimeout = 200 * time.Millisecond
-	defer func() { discoveryPingTimeout = prev }()
-
 	ping := []byte{proto.UnconnectedPingOpenID, 1, 2, 3, 4, 5, 6, 7, 8}
 	if err := p.HandleUnconnectedPing(ping, client.LocalAddr()); err != nil {
 		t.Fatalf("HandleUnconnectedPing 0x02: %v", err)

internal/proxy/proxy.go

@@ -38,14 +38,31 @@ const offlineTimeoutThreshold = 3
 
 var idleCheckInterval = 5 * time.Second
 
-// discoveryPingTimeout bounds how long a LAN probe waits for upstream. Keep this
-// below compat PingTimeout (2s) so clients pinging the bind port get a timely reply.
-var discoveryPingTimeout = 1500 * time.Millisecond
+// Discovery probe deadlines (nanoseconds). Stored atomically so tests can shorten
+// them without racing the background health-check goroutine.
+var (
+	discoveryPingTimeoutNanos          atomic.Int64
+	discoveryRecoveryProbeTimeoutNanos atomic.Int64
+	discoveryHealthIntervalNanos       atomic.Int64
+)
+
+func init() {
+	discoveryPingTimeoutNanos.Store(int64(1500 * time.Millisecond))
+	discoveryRecoveryProbeTimeoutNanos.Store(int64(500 * time.Millisecond))
+	discoveryHealthIntervalNanos.Store(int64(2 * time.Second))
+}
+
+func discoveryPingTimeout() time.Duration {
+	return time.Duration(discoveryPingTimeoutNanos.Load())
+}
+
+func discoveryRecoveryProbeTimeout() time.Duration {
+	return time.Duration(discoveryRecoveryProbeTimeoutNanos.Load())
+}
 
-// discoveryRecoveryProbeTimeout is used once the server is already marked offline:
-// a quick check whether upstream came back without making every LAN ping wait out
-// the full discoveryPingTimeout.
-var discoveryRecoveryProbeTimeout = 500 * time.Millisecond
+func discoveryHealthInterval() time.Duration {
+	return time.Duration(discoveryHealthIntervalNanos.Load())
+}
 
 type ProxyServer struct {
 	bindAddress         *net.UDPAddr
@@ -185,6 +202,10 @@ func (proxy *ProxyServer) listen() error {
 	}
 	proxy.server.Store(proxyServer)
 
+	// Learn offline/online before the first console ping, and recover without
+	// making OfflinePong wait on a synchronous probe.
+	proxy.startUpstreamHealthCheck()
+
 	return nil
 }
 
@@ -438,6 +459,18 @@ func (proxy *ProxyServer) handleDiscoveryPing(client net.Addr, ping []byte) erro
 		return fmt.Errorf("proxy not running")
 	}
 
+	// Already offline: reply immediately. Waiting on a recovery probe made
+	// OfflinePong arrive after console discovery timeouts — blackholed remotes
+	// take the full deadline, so the LAN entry never appeared even though logs
+	// later showed a pong was sent.
+	if proxy.isServerOffline() {
+		if _, err := server.WriteTo(proxy.buildOfflinePong(ping), client); err != nil {
+			return err
+		}
+		log.Info().Msgf("Sent server offline pong to client: %v", client.String())
+		return nil
+	}
+
 	pong, err := proxy.probeRemoteUnconnectedPong(ping)
 	if err != nil {
 		proxy.markServerOffline()
@@ -458,6 +491,49 @@ func (proxy *ProxyServer) handleDiscoveryPing(client net.Addr, ping []byte) erro
 	return nil
 }
 
+// startUpstreamHealthCheck probes the remote on a timer so OfflinePong can be
+// advertised before the first LAN ping, and so recovery does not require a
+// client to wait out a synchronous probe.
+func (proxy *ProxyServer) startUpstreamHealthCheck() {
+	go func() {
+		proxy.probeUpstreamHealth()
+		ticker := time.NewTicker(discoveryHealthInterval())
+		defer ticker.Stop()
+		for {
+			select {
+			case <-ticker.C:
+				if proxy.dead.IsSet() {
+					return
+				}
+				proxy.probeUpstreamHealth()
+			}
+		}
+	}()
+}
+
+func (proxy *ProxyServer) probeUpstreamHealth() {
+	if proxy.dead.IsSet() || proxy.dataConn() == nil {
+		return
+	}
+	_, err := proxy.probeRemoteUnconnectedPong(healthCheckPing())
+	if err != nil {
+		proxy.markServerOffline()
+		return
+	}
+	proxy.noteUpstreamReachable()
+}
+
+// healthCheckPing is a minimal valid Unconnected Ping for background probes.
+func healthCheckPing() []byte {
+	magic := []byte{0x00, 0xff, 0xff, 0x00, 0xfe, 0xfe, 0xfe, 0xfe, 0xfd, 0xfd, 0xfd, 0xfd, 0x12, 0x34, 0x56, 0x78}
+	out := make([]byte, 0, 1+8+8+16)
+	out = append(out, proto.UnconnectedPingID)
+	out = append(out, 0, 0, 0, 0, 0, 0, 0, 0) // ping time
+	out = append(out, 0, 0, 0, 0, 0, 0, 0, 0) // client GUID
+	out = append(out, magic...)
+	return out
+}
+
 // probeRemoteUnconnectedPong dials a one-shot UDP socket to the remote and
 // waits for an Unconnected Pong. A fresh local port avoids stale RakNet state.
 func (proxy *ProxyServer) probeRemoteUnconnectedPong(ping []byte) ([]byte, error) {
@@ -467,9 +543,9 @@ func (proxy *ProxyServer) probeRemoteUnconnectedPong(ping []byte) ([]byte, error
 	}
 	defer conn.Close()
 
-	timeout := discoveryPingTimeout
+	timeout := discoveryPingTimeout()
 	if proxy.isServerOffline() {
-		timeout = discoveryRecoveryProbeTimeout
+		timeout = discoveryRecoveryProbeTimeout()
 	}
 	_ = conn.SetDeadline(time.Now().Add(timeout))
 	if _, err := conn.Write(ping); err != nil {

internal/proxy/udp_recv_buffer_test.go

@@ -5,6 +5,8 @@ import (
 	"net"
 	"testing"
 	"time"
+
+	"github.com/jhead/phantom/internal/proto"
 )
 
 func TestUDPRecvBufferCoversOversizedRakNetDatagrams(t *testing.T) {
@@ -60,19 +62,13 @@ func TestProxyForwardsLargeDatagramsBothWays(t *testing.T) {
 	}
 	defer remote.Close()
 
-	// Exclusive :19132 bind in Start() — skip cleanly if another phantom owns it.
-	probe, err := net.ListenPacket("udp4", "127.0.0.1:19132")
-	if err != nil {
-		t.Skipf("port 19132 unavailable: %v", err)
-	}
-	probe.Close()
-
 	p, err := New(ProxyPrefs{
-		BindAddress:  "127.0.0.1",
-		BindPort:     0,
-		RemoteServer: remote.LocalAddr().String(),
-		IdleTimeout:  time.Minute,
-		NumWorkers:   1,
+		BindAddress:              "127.0.0.1",
+		BindPort:                 0,
+		RemoteServer:             remote.LocalAddr().String(),
+		IdleTimeout:              time.Minute,
+		NumWorkers:               1,
+		DisableDiscoveryListener: true,
 	})
 	if err != nil {
 		t.Fatal(err)
@@ -111,11 +107,21 @@ func TestProxyForwardsLargeDatagramsBothWays(t *testing.T) {
 			t.Fatalf("client write %d: %v", size, err)
 		}
 
-		_ = remote.SetReadDeadline(time.Now().Add(time.Second))
 		rbuf := make([]byte, udpRecvBufferSize)
-		rn, from, err := remote.ReadFrom(rbuf)
-		if err != nil {
-			t.Fatalf("remote read %d: %v", size, err)
+		var rn int
+		var from net.Addr
+		readDeadline := time.Now().Add(2 * time.Second)
+		for {
+			_ = remote.SetReadDeadline(readDeadline)
+			rn, from, err = remote.ReadFrom(rbuf)
+			if err != nil {
+				t.Fatalf("remote read %d: %v", size, err)
+			}
+			// Background health checks send Unconnected Pings; skip them.
+			if rn >= 1 && proto.IsUnconnectedDiscoveryPing(rbuf[0]) {
+				continue
+			}
+			break
 		}
 		if rn != size || !bytes.Equal(rbuf[:rn], up) {
 			t.Fatalf("upstream got n=%d want %d (truncated or corrupt)", rn, size)