Document Android network change detection limitation

MobileLibrary/Android/PsiphonTunnel/PsiphonTunnel.java

@@ -1649,6 +1649,24 @@ public class PsiphonTunnel {
                     // If we are NOT in the VPN mode then monitor default active networks with the
                     // Internet capability, including VPN, to ensure we won't trigger a reconnect in
                     // case the VPN is up while the system switches the underlying network.
+
+                    // Limitation: for Psiphon Library apps running over Psiphon VPN, or other VPNs
+                    // with a similar architecture, it may be better to trigger a reconnect when
+                    // the underlying physical network changes. When the underlying network
+                    // changes, Psiphon VPN will remain up and reconnect its own tunnel. For the
+                    // Psiphon app, this monitoring will detect no change. However, the Psiphon
+                    // app's tunnel may be lost, and, without network change detection, initiating
+                    // a reconnect will be delayed. For example, if the Psiphon app's tunnel is
+                    // using QUIC, the Psiphon VPN will tunnel that traffic over udpgw. When
+                    // Psiphon VPN reconnects, the egress source address of that UDP flow will
+                    // change -- getting either a different source IP if the Psiphon server
+                    // changes, or a different source port even if the same server -- and the QUIC
+                    // server will drop the packets. The Psiphon app will initiate a reconnect only
+                    // after a SSH keep alive probes timeout or a QUIC timeout.
+                    //
+                    // TODO: Add a second ConnectivityManager/NetworkRequest instance to monitor
+                    // for underlying physical network changes while any VPN remains up.
+
                     builder.removeCapability(NetworkCapabilities.NET_CAPABILITY_NOT_VPN);
                 }