Add detailed docs & sprinkle logging in the VPN internals

Author: pimterry

app/src/main/java/tech/httptoolkit/android/vpn/README.md

@@ -1,7 +1,20 @@
-# ToyShark VPN packet capture implementation
+# Android packet-intercepting VPN
 
-This package contains the logic that captures and then forwards packets.
+This package contains the logic that captures and then forwards packets, on device, using the Android VPN interface.
 
-It's been heavily edited, but is originally based on [ToyShark](https://github.com/LipiLee/ToyShark/tree/0963ad8bda35cd2b2e8e0ea0a47873683b604453) (under the Apache 2 license).
+It provides the components (woven together in ProxyVpnRunnable) that read raw IP packets from the VPN interface, parse them, make the corresponding upstream TCP/UDP requests, and proxy data between the two.
 
-The full source & license is available from that URL.
+The code has been very heavily edited, but was originally based on [ToyShark](https://github.com/LipiLee/ToyShark/tree/0963ad8bda35cd2b2e8e0ea0a47873683b604453), which was in turn based on AT&T's [ARO project](https://github.com/attdevsupport/ARO/), all used under the Apache 2 license. The full original source & license is available from those repo URLs.
+
+## Details
+
+Some quick notes on how this all hangs together:
+
+* The VPN interface gives us a file descriptor, from which we can read & write raw IP packets.
+* On Android we can't actually send or receive raw IP packets from upstream, without native code, at least.
+* To handle this, we parse the IP packets, work out how to do the equivalent TCP/UDP/ICMP upstream, do it, and proxy between that & the VPN interface/
+* SessionHandler handles the VPN packet side of this: it receives IP packets in `handlePacket` from a thread that loops on `vpn.read()`, handles ACKs etc, and makes calls to `SessionManager` to create/close upstream connections when required.
+* SessionManager allows opening and closing upstream sessions and their channels (TCP/UDP connections), registering each channel with `SocketNIODataService`.
+* SocketNIODataService runs on a single thread, using NIO to write VPN-received data from the session to the upstream channel when the channel is available, and to read data from upstream channels when it's received.
+* Data is sent back into the VPN (by both SessionHandler and the NIO thread) via ClientPacketWriter, which runs on its own thread, looping on a blocking queue to do each requested write.
+* SessionManager can be configured with traffic redirections, to redirect traffic on certain ports to different destinations (e.g. all outgoing traffic on 80/443 to a transparent proxy server).

app/src/main/java/tech/httptoolkit/android/vpn/SessionHandler.java

@@ -405,6 +405,7 @@ private void handleICMPPacket(
 		final IPv4Header ipHeader
 	) throws PacketHeaderException {
 		final ICMPPacket requestPacket = ICMPPacketFactory.parseICMPPacket(clientPacketData);
+		Log.d(TAG, "Got an ICMP ping packet, type " + requestPacket.toString());
 
 		pingThreadpool.execute(new Runnable() {
 			@Override
@@ -435,8 +436,7 @@ public void run() {
 
 			private boolean isReachable(String ipAddress) {
 				try {
-					InetAddress destAddr = InetAddress.getByName(ipAddress);
-					return destAddr.isReachable(10000);
+					return InetAddress.getByName(ipAddress).isReachable(10000);
 				} catch (IOException e) {
 					return false;
 				}

app/src/main/java/tech/httptoolkit/android/vpn/socket/SocketChannelReader.java

@@ -124,11 +124,13 @@ private void readTCP(@NonNull Session session) {
 	}
 
 	private void sendToRequester(ByteBuffer buffer, int dataSize, @NonNull Session session){
-		//last piece of data is usually smaller than MAX_RECEIVE_BUFFER_SIZE
-		if(dataSize < DataConst.MAX_RECEIVE_BUFFER_SIZE)
+		// Last piece of data is usually smaller than MAX_RECEIVE_BUFFER_SIZE. We use this as a
+		// trigger to set PSH on the resulting TCP packet that goes to the VPN.
+		if (dataSize < DataConst.MAX_RECEIVE_BUFFER_SIZE) {
 			session.setHasReceivedLastSegment(true);
-		else
+		} else {
 			session.setHasReceivedLastSegment(false);
+		}
 
 		buffer.limit(dataSize);
 		buffer.flip();

app/src/main/java/tech/httptoolkit/android/vpn/socket/SocketChannelWriter.java

@@ -43,7 +43,8 @@ public void write(@NonNull Session session) {
 		} else if(channel instanceof DatagramChannel) {
 			writeUDP(session);
 		} else {
-			return;
+			// We only ever create TCP & UDP channels, so this should never happen
+			throw new IllegalArgumentException("Unexpected channel type: " + channel);
 		}
 
 		if(session.isAbortingConnection()){