Add comments

psiphon/common/inproxy/quality.go

@@ -553,7 +553,8 @@ func (r *ProxyQualityReporter) prepareNextRequest() ProxyQualityRequestCounts {
 
 	queueEntry := r.reportQueue.Front()
 
-	// Limit the size of each request to maxRequestEntries.
+	// Limit the size of each request, capping both the memory overhead and
+	// the amount of data lost in a temporary network disruption.
 	//
 	// Limitation: maxRequestEntries doesn't take into account the number of
 	// different client ASN counts per entry. In practice, there shouldn't be

psiphon/notice.go

@@ -1126,8 +1126,8 @@ func NoticeInproxyMustUpgrade() {
 // for activity since the last NoticeInproxyProxyActivity report.
 //
 // This is not a diagnostic notice: the user app has requested this notice
-// with EmitproxyActivity for functionality such as traffic display; and this
-// frequent notice is not intended to be included with feedback.
+// with EmitInproxyProxyActivity for functionality such as traffic display;
+// and this frequent notice is not intended to be included with feedback.
 func NoticeInproxyProxyActivity(
 	connectingClients int32,
 	connectedClients int32,

psiphon/server/bpf.go

@@ -100,6 +100,11 @@ func getBPFProgram(support *SupportServices) (bool, string, []bpf.RawInstruction
 		return false, "", nil, nil
 	}
 
+	// Use a consistent seed for the PRNG so that, for a fixed probability
+	// setting, servers consistently select whether to apply the BPF program
+	// or not; this is intended to present a stable server behavior
+	// fingerprint.
+
 	seed, err := protocol.DeriveBPFServerProgramPRNGSeed(support.Config.ObfuscatedSSHKey)
 	if err != nil {
 		return false, "", nil, errors.Trace(err)

psiphon/server/tunnelServer.go

@@ -2717,6 +2717,26 @@ func (sshClient *sshClient) run(
 	replayMetrics["server_replay_packet_manipulation"] = sshClient.replayedServerPacketManipulation
 	additionalMetrics = append(additionalMetrics, replayMetrics)
 
+	// Log the server_tunnel event. This log is only guaranteed to be recorded
+	// after the SSH handshake completes successfully. If the tunnel fails or
+	// is aborted by the client after that point, there will be a server_tunnel
+	// log -- with handshake_completed false, if the failure is during the
+	// liveness test or Psiphon API handshake, and handshake_completed true
+	// otherwise.
+	//
+	// Some scenarios where there is no server_tunnel log, despite a client
+	// initiating a dial, can include:
+	// - Failure during the TCP handshake.
+	// - Connecting to a fronting CDN, but not establishing a full meek session.
+	// - Failure during QUIC, TLS, or Obfuscated OSSH handshakes and all other
+	//   obfuscation layers which come before the SSH handshake.
+	// - The server being in the load limiting state, SetEstablishTunnels(false)
+	//
+	// In the case of the outermost application-level network protocol,
+	// including SSH, we do not necessarly want to log any server_tunnel
+	// event until the client has passed anti-probing checks; otherwise, the
+	// peer may not be a legitimate client.
+
 	// Limitation: there's only one log per tunnel with bytes transferred
 	// metrics, so the byte count can't be attributed to a certain day for
 	// tunnels that remain connected for well over 24h. In practise, most

psiphon/tunnel.go

@@ -2172,6 +2172,19 @@ loop:
 			!isShutdown &&
 			!wasHandled {
 
+			// Note that tunnel.dialParams.Failed is not called in this failed
+			// tunnel case, and any replay parameters are retained.
+			//
+			// The continuousNetworkConnectivity mechanism is an imperfect
+			// best-effort to filter out bad network conditions, and isn't
+			// enabled on platforms without NetworkConnectivityChecker. There
+			// remains a possibility of failure due to innocuous bad network
+			// conditions and perhaps device sleep cycles.
+			//
+			// Furthermore, at this point the tunnel has already passed any
+			// pre-handshake liveness test, which is intended to catch cases
+			// of late-life cycle blocking.
+
 			_ = RecordFailedTunnelStat(
 				tunnel.config,
 				tunnel.dialParams,