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
if SCNetworkReachabilityGetFlags(reachability, &flags) {
connection.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
let socket = socket(AF_INET, SOCK_STREAM, 0)
connect(socket, &addr, addrlen)
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
var hints = addrinfo(...)
getaddrinfo("example.com", "443", &hints, &results)
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
let host = "192.168.1.1"
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
connection.stateUpdateHandler = { state in
if case .ready = state {
}
}
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
connection.send(content: data, completion: .contentProcessed { error in
self.handleSend(error)
})
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+)
Task {
let connection = NetworkConnection(...)
connection.send(data)
connection.stateUpdateHandler = { ... }
}
Why this fails NetworkConnection designed for pure async/await. Mixing paradigms creates difficult error propagation and cancellation issues.
8. Not supporting network transitions
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:
URLSession.shared.dataTask(with: url) { ... }
if #available(iOS 26, *) {
} else {
}
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
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)
✅ GOOD: NetworkConnection with Declarative Stack
import Network
let connection = NetworkConnection(
to: .hostPort(host: "www.example.com", port: 1029)
) {
TLS()
}
public func sendAndReceiveWithTLS() async throws {
let outgoingData = Data("Hello, world!".utf8)
try await connection.send(outgoingData)
let incomingData = try await connection.receive(exactly: 98)
