Recover P2P and Relay peer connections immediately after Android network handover

[hchengting]

Before posting

• I searched existing discussions and issues, including closed ones, and checked the relevant docs.
• I believe this is a product bug rather than a configuration or setup question.
• I can reproduce this issue, or for intermittent issues I've included trigger, frequency, and timing details below.
• I removed or anonymized sensitive data from logs, screenshots, and configuration.

Affected area

Client / Agent, Mobile app, Peer connectivity, Relay / Signal / NAT traversal

Deployment type

Self-hosted - quickstart script

Operating system or environment

Linux, Android

NetBird version and upgrade status

• Client: dev-310f9cca3
• Management: 0.77.0
• Signal: 0.77.0
• Relay: 0.77.0
• Dashboard: 2.91.1

Did this work before?

No, this never worked

Regression details

No response

Summary

When an Android client switches between Wi-Fi and mobile data, peer connections
can remain logically connected even though their sockets belong to the previous
network and can no longer carry traffic.

The Android device already has a usable network again, and Management, Signal,
or Relay infrastructure connections may have recovered, but traffic to the peer
remains unavailable until the peer transport detects the failure through its
normal timeout path.

The client should proactively invalidate peer transports bound to the previous
network and rebuild them as soon as the required infrastructure is ready.

Current behavior

Direct P2P/ICE

After Android changes its default network, the ICE sockets created on the old
network can silently become unusable.

The ICE agent can continue reporting the session as connected until its
disconnected and failed timeouts expire. Peer traffic remains unavailable
during this interval even though Signal connectivity has already recovered.

NetBird Relay

When the active peer path uses NetBird Relay, the Relay server connection may
reconnect on the new network before the per-peer Relay connection becomes
usable again.

In testing, peer traffic remains unavailable for approximately 10 additional
seconds after the network transition. Recovery depends on the normal Relay
disconnect callback, connectivity guard, and offer/answer retry flow instead of
being triggered directly by the OS network-change event.

Expected behavior

After Android switches between Wi-Fi and mobile data:

• Peer transports associated with the old network are invalidated.
• Reconnection begins when the required Signal and Relay infrastructure is
  ready on the new network.
• Direct P2P recovery does not wait for the ICE disconnected and failed
  timeouts.
• Relay recovery does not wait for an additional timeout or periodic check.
• The engine and NetBird interface remain running.
• Existing peer state cannot incorrectly remain connected while traffic is
  unavailable.

Steps to reproduce

Direct P2P

1. Connect an Android client to another NetBird peer using a direct P2P path.
2. Confirm the connection type using status output or debug logs.
3. Start continuous traffic between the peers.
4. Switch the Android device from Wi-Fi to mobile data, or from mobile data to
   Wi-Fi.
5. Observe that peer traffic stops.
6. Observe that recovery waits for ICE to detect that the old session is no
   longer usable.

Relay

1. Connect an Android client to another NetBird peer.
2. Prevent a direct ICE path or enable force-relay mode.
3. Confirm that the peer connection uses NetBird Relay.
4. Start continuous traffic between the peers.
5. Switch the Android device between Wi-Fi and mobile data.
6. Observe the Relay server reconnection timestamp.
7. Observe that peer traffic remains unavailable for approximately 10
   additional seconds.

Environment and topology

• Peer A: Android with NAT/mobile network
• Peer B: Linux with public IP

Self-hosted details, if available

No response

Logs, status output, or debug evidence

fb7590f3a47ce053b50664d300cc5d3f5846d0578b908cd14745a536f0a70da2/a126c4d8-05fa-49e0-ab5e-fdbcb3e26347

Related issues or discussions

• Android-App: Netbird not reconnecting when switching between wifi and cellular #2029
• Netbird keeps disconnecting android-client#146
• [client, android] Handle network changes without restarting the engine #7144
• fix: notify Go core on seamless network handover (cellular → WiFi) while VPN is active android-client#243

Impact

• Affected users: Android users whose peer connectivity depends on NetBird Relay
• Impact: active tunnels temporarily stop carrying traffic whenever the device
  moves between Wi-Fi and mobile data
• Workaround: wait for the existing reconnection timeout, or restart the
  connection manually

Additional context

Cause

The OS network-change notification currently restores infrastructure
connectivity, but peer transports can retain state created on the previous
network.

For ICE:

• The ICE agent owns sockets bound to the previous network.
• The sockets can fail silently.
• Recovery depends on ICE timeout processing unless the session is explicitly
  invalidated.

For Relay:

• The Relay manager owns the shared connection to the Relay server.
• Each peer also owns a logical Relay connection and a local Relay proxy.
• Restoring the shared Relay server connection does not by itself guarantee
  that every per-peer Relay connection has been retired and recreated.
• The peer may wait for a later disconnect callback or reconnect attempt before
  sending a fresh offer.

Proposed solution

Propagate the Android network-change event to every open peer connection and
invalidate all network-bound peer transports.

ICE handling

For each ICE worker:

1. Detach the ICE agent associated with the previous network.
2. Cancel any ICE dial or negotiation still using the old network.
3. Rotate the ICE session ID so the remote peer treats the next offer as a new
   session.
4. Close the old ICE agent outside worker and peer locks.
5. Mark ICE disconnected and wake the peer connectivity guard.
6. Send a fresh offer after Signal is ready.

Closing the agent must not happen while holding a lock used by its final state
callback.

Relay handling

For each peer Relay connection:

1. Identify the logical Relay connection and proxy associated with the previous
   network generation.
2. Detach them from the peer state before closing network resources.
3. Prevent an old proxy's disconnect callback from modifying a replacement
   connection.
4. Close the old logical Relay connection and proxy outside peer and worker
   locks.
5. Mark the Relay transport disconnected.
6. If Relay was active, remove the stale peer endpoint and reset the active
   connection priority.
7. If ICE was active and Relay was only the fallback, preserve the active ICE
   endpoint and remove only the stale Relay fallback.
8. Wake the connectivity guard.
9. When Signal and Relay are ready on the new network, send a fresh offer and
   open a new per-peer Relay connection.

The same flow must work when Relay is the only available transport.