axiom-networking

Network.framework Networking

When to Use This Skill

Use when:

• Implementing UDP/TCP connections for gaming, streaming, or messaging apps
• Migrating from BSD sockets, CFSocket, NSStream, or SCNetworkReachability
• Debugging connection timeouts or TLS handshake failures
• Supporting network transitions (WiFi ↔ cellular) gracefully
• Adopting structured concurrency networking patterns (iOS 26+)
• Implementing custom protocols over TLS/QUIC
• Requesting code review of networking implementation before shipping

Related Skills

• Use axiom-networking-diag for systematic troubleshooting of connection failures, timeouts, and performance issues
• Use axiom-network-framework-ref for comprehensive API reference with all WWDC examples

Example Prompts

1. "How do I migrate from SCNetworkReachability? My app checks connectivity before connecting."

2. "My connection times out after 60 seconds. How do I debug this?"

3. "Should I use NWConnection or NetworkConnection? What's the difference?"

---

Red Flags — Anti-Patterns to Prevent

If you're doing ANY of these, STOP and use the patterns in this skill:

❌ CRITICAL — Never Do These

1. Using SCNetworkReachability to check connectivity before connecting

// ❌ WRONG — Race condition
if SCNetworkReachabilityGetFlags(reachability, &flags) {
    connection.start() // Network may change between check and start
}

Why this fails Network state changes between reachability check and connect(). You miss Network.framework's smart connection establishment (Happy Eyeballs, proxy handling, WiFi Assist). Apple deprecated this API in 2018.

2. Blocking socket operations on main thread

// ❌ WRONG — Guaranteed ANR (Application Not Responding)
let socket = socket(AF_INET, SOCK_STREAM, 0)
connect(socket, &addr, addrlen) // Blocks main thread

Why this fails Main thread hang → frozen UI → App Store rejection for responsiveness. Even "quick" connects take 200-500ms.

3. Manual DNS resolution with getaddrinfo

// ❌ WRONG — Misses Happy Eyeballs, proxies, VPN
var hints = addrinfo(...)
getaddrinfo("example.com", "443", &hints, &results)
// Now manually try each address...

Why this fails You reimplement 10+ years of Apple's connection logic poorly. Misses IPv4/IPv6 racing, proxy evaluation, VPN detection.

4. Hardcoded IP addresses instead of hostnames

// ❌ WRONG — Breaks proxy/VPN compatibility
let host = "192.168.1.1" // or any IP literal

Why this fails Proxy auto-configuration (PAC) needs hostname to evaluate rules. VPNs can't route properly. DNS-based load balancing broken.

5. Ignoring waiting state — not handling lack of connectivity

// ❌ WRONG — Poor UX
connection.stateUpdateHandler = { state in
    if case .ready = state {
        // Handle ready
    }
    // Missing: .waiting case
}

Why this fails User sees "Connection failed" in Airplane Mode instead of "Waiting for network." No automatic retry when WiFi returns.

6. Not using [weak self] in NWConnection completion handlers

// ❌ WRONG — Memory leak
connection.send(content: data, completion: .contentProcessed { error in
    self.handleSend(error) // Retain cycle: connection → handler → self → connection
})

Why this fails Connection retains completion handler, handler captures self strongly, self retains connection → memory leak.

7. Mixing async/await and completion handlers in NetworkConnection (iOS 26+)

// ❌ WRONG — Structured concurrency violation
Task {
    let connection = NetworkConnection(...)
    connection.send(data) // async/await
    connection.stateUpdateHandler = { ... } // completion handler — don't mix
}

Why this fails NetworkConnection designed for pure async/await. Mixing paradigms creates difficult error propagation and cancellation issues.

8. Not supporting network transitions

// ❌ WRONG — Connection fails on WiFi → cellular transition
// No viabilityUpdateHandler, no betterPathUpdateHandler
// User walks out of building → connection dies

Why this fails Modern apps must handle network changes gracefully. 40% of connection failures happen during network transitions.

---

Mandatory First Steps

ALWAYS complete these steps before writing any networking code:

// Step 1: Identify your use case
// Record: "UDP gaming" vs "TLS messaging" vs "Custom protocol over QUIC"
// Ask: What data am I sending? Real-time? Reliable delivery needed?

// Step 2: Check if URLSession is sufficient
// URLSession handles: HTTP, HTTPS, WebSocket, TCP/TLS streams (via StreamTask)
// Network.framework handles: UDP, custom protocols, low-level control, peer-to-peer

// If HTTP/HTTPS/WebSocket → STOP, use URLSession instead
// Example:
URLSession.shared.dataTask(with: url) { ... } // ✅ Correct for HTTP

// Step 3: Choose API version based on deployment target
if #available(iOS 26, *) {
    // Use NetworkConnection (structured concurrency, async/await)
    // TLV framing built-in, Coder protocol for Codable types
} else {
    // Use NWConnection (completion handlers)
    // Manual framing or custom framers
}

// Step 4: Verify you're NOT using deprecated APIs
// Search your codebase for these:
// - SCNetworkReachability → Use connection waiting state
// - CFSocket → Use NWConnection
// - NSStream, CFStream → Use NWConnection
// - NSNetService → Use NWBrowser or NetworkBrowser
// - getaddrinfo → Let Network.framework handle DNS

// To search:
// grep -rn "SCNetworkReachability\|CFSocket\|NSStream\|getaddrinfo" .

What this tells you

• If HTTP/HTTPS: Use URLSession, not Network.framework
• If iOS 26+ deployment: Use NetworkConnection with async/await
• If iOS 12-25 support needed: Use NWConnection with completion handlers
• If any deprecated API found: Must migrate before shipping (App Store review concern)

---

Decision Tree

Use this to select the correct pattern in 2 minutes:

Need networking?
├─ HTTP, HTTPS, or WebSocket?
│  └─ YES → Use URLSession (NOT Network.framework)
│     ✅ URLSession.shared.dataTask(with: url)
│     ✅ URLSession.webSocketTask(with: url)
│     ✅ URLSession.streamTask(withHostName:port:) for TCP/TLS
│
├─ iOS 26+ and can use structured concurrency?
│  └─ YES → NetworkConnection path (async/await)
│     ├─ TCP with TLS security?
│     │  └─ Pattern 1a: NetworkConnection + TLS
│     │     Time: 10-15 minutes
│     │
│     ├─ UDP for gaming/streaming?
│     │  └─ Pattern 1b: NetworkConnection + UDP
│     │     Time: 10-15 minutes
│     │
│     ├─ Need message boundaries (framing)?
│     │  └─ Pattern 1c: TLV Framing
│     │     Type-Length-Value for mixed message types
│     │     Time: 15-20 minutes
│     │
│     └─ Send/receive Codable objects directly?
│        └─ Pattern 1d: Coder Protocol
│           No manual JSON encoding needed
│           Time: 10-15 minutes
│
└─ iOS 12-25 or need completion handlers?
   └─ YES → NWConnection path (callbacks)
      ├─ TCP with TLS security?
      │  └─ Pattern 2a: NWConnection + TLS
      │     stateUpdateHandler, completion-based send/receive
      │     Time: 15-20 minutes
      │
      ├─ UDP streaming with batching?
      │  └─ Pattern 2b: NWConnection + UDP Batch
      │     connection.batch for 30% CPU reduction
      │     Time: 10-15 minutes
      │
      ├─ Listening for incoming connections?
      │  └─ Pattern 2c: NWListener
      │     Accept inbound connections, newConnectionHandler
      │     Time: 20-25 minutes
      │
      └─ Network discovery (Bonjour)?
         └─ Pattern 2d: NWBrowser
            Discover services on local network
            Time: 25-30 minutes

Quick selection guide

• Gaming (low latency, some loss OK) → UDP patterns (1b or 2b)
• Messaging (reliable, ordered) → TLS patterns (1a or 2a)
• Mixed message types → TLV or Coder (1c or 1d)
• Peer-to-peer → Discovery patterns (2d) + incoming (2c)

---

Common Patterns

Pattern 1a: NetworkConnection with TLS (iOS 26+)

Use when iOS 26+ deployment, need reliable TCP with TLS security, want async/await

Time cost 10-15 minutes

❌ BAD: Manual DNS, Blocking Socket

// WRONG — Don't do this
var hints = addrinfo(...)
getaddrinfo("www.example.com", "1029", &hints, &results)
let sock = socket(AF_INET, SOCK_STREAM, 0)
connect(sock, results.pointee.ai_addr, results.pointee.ai_addrlen) // Blocks!

✅ GOOD: NetworkConnection with Declarative Stack

import Network

// Basic connection with TLS
let connection = NetworkConnection(
    to: .hostPort(host: "www.example.com", port: 1029)
) {
    TLS() // TCP and IP inferred automatically
}

// Send and receive with async/await
public func sendAndReceiveWithTLS() async throws {
    let outgoingData = Data("Hello, world!".utf8)
    try await connection.send(outgoingData)

    let incomingData = try await connection.receive(exactly: 98).content
    print("Received data: \(incomingData)")
}

// Optional: Monitor connection state for UI updates
Task {
    for await state in connection.states {
        switch state {
        case .preparing:
            print("Establishing connection...")
        case .ready:
            print("Connected!")
        case .waiting(let error):
            print("Waiting for network: \(error)")
        case .failed(let error):
            print("Connection failed: \(error)")
        case .cancelled:
            print("Connection cancelled")
        @unknown default:
            break
        }
    }
}

Custom parameters for low data mode

let connection = NetworkConnection(
    to: .hostPort(host: "www.example.com", port: 1029),
    using: .parameters {
        TLS {
            TCP {
                IP()
                    .fragmentationEnabled(false)
            }
        }
    }
    .constrainedPathsProhibited(true) // Don't use cellular in low data mode
)

When to use

• Secure messaging, email protocols (IMAP, SMTP)
• Custom p

---

Content truncated.