axiom-networking-diag

Network.framework Diagnostics

Overview

Core principle 85% of networking problems stem from misunderstanding connection states, not handling network transitions, or improper error handling—not Network.framework defects.

Network.framework is battle-tested in every iOS app (powers URLSession internally), handles trillions of requests daily, and provides smart connection establishment with Happy Eyeballs, proxy evaluation, and WiFi Assist. If your connection is failing, timing out, or behaving unexpectedly, the issue is almost always in how you're using the framework, not the framework itself.

This skill provides systematic diagnostics to identify root causes in minutes, not hours.

Red Flags — Suspect Networking Issue

If you see ANY of these, suspect a networking misconfiguration, not framework breakage:

• Connection times out after 60 seconds with no clear error

• TLS handshake fails with "certificate invalid" on some networks

• Data sent but never arrives at receiver

• Connection drops when switching WiFi to cellular

• Works perfectly on WiFi but fails 100% of time on cellular

• Works in simulator but fails on real device

• Connection succeeds on your network but fails for users

• ❌ FORBIDDEN "Network.framework is broken, we should rewrite with sockets"

  • Network.framework powers URLSession, used in every iOS app
  • Handles edge cases you'll spend months discovering with sockets
  • Apple engineers have 10+ years of production debugging baked into framework
  • Switching to sockets will expose you to 100+ edge cases

Critical distinction Simulator uses macOS networking stack (not iOS), hides cellular-specific issues (IPv6-only networks), and doesn't simulate network transitions. MANDATORY: Test on real device with real network conditions.

Mandatory First Steps

ALWAYS run these commands FIRST (before changing code):

// 1. Enable Network.framework logging
// Add to Xcode scheme: Product → Scheme → Edit Scheme → Arguments
// -NWLoggingEnabled 1
// -NWConnectionLoggingEnabled 1

// 2. Check connection state history
connection.stateUpdateHandler = { state in
    print("\(Date()): Connection state: \(state)")
    // Log every state transition with timestamp
}

// 3. Check TLS configuration
// If using custom TLS parameters:
print("TLS version: \(tlsParameters.minimumTLSProtocolVersion)")
print("Cipher suites: \(tlsParameters.tlsCipherSuites ?? [])")

// 4. Test with packet capture (Charles Proxy or Wireshark)
// On device: Settings → WiFi → (i) → Configure Proxy → Manual
// Charles: Help → SSL Proxying → Install Charles Root Certificate on iOS

// 5. Test on different networks
// - WiFi
// - Cellular (disable WiFi)
// - Airplane Mode → WiFi (test waiting state)
// - VPN active
// - IPv6-only (some cellular carriers)