Swift Networking

Swift Networking

Network.framework is Apple's modern networking API for TCP/UDP connections, replacing BSD sockets with smart connection establishment, user-space networking, and seamless mobility handling.

Reference Loading Guide

ALWAYS load reference files if there is even a small chance the content may be required. It's better to have the context than to miss a pattern or make a mistake.

Core Workflow

1. Choose transport (TCP/UDP/QUIC) based on use case 2. Create NWConnection (iOS 12+) or NetworkConnection (iOS 26+) 3. Set up state handler for connection lifecycle 4. Start connection on appropriate queue 5. Send/receive data with proper error handling 6. Handle network transitions (WiFi to cellular)

When to Use Network.framework vs URLSession

• URLSession: HTTP, HTTPS, WebSocket, simple TCP/TLS streams
• Network.framework: UDP, custom protocols, low-level control, peer-to-peer, gaming

Common Mistakes

1. Ignoring state handlers — Creating an NWConnection without a state change handler means you never learn when it's ready or failed. Always implement the state handler first.

2. Blocking the main thread — Never call receive() on the main queue. Use a background DispatchQueue or Task for all network operations.

3. Wrong queue selection — Using the wrong queue (UI queue for network work, or serial queue for concurrent reads) causes deadlocks or silent failures. Always explicit your queue choice.

4. Not handling network transitions — WiFi/cellular switches or network loss aren't always detected automatically. Implement viability checks and state monitoring for robust apps.

5. Improper error recovery — Network errors need retry logic with backoff. Immediately failing on transient errors (timeouts, temporary loss) creates poor UX.

Connection State Handling

State Machine

setup -> preparing -> waiting <-> ready -> failed/cancelled

State Handling (iOS 12+)

connection.stateUpdateHandler = { [weak self] state in
    switch state {
    case .preparing:
        self?.updateUI(.connecting)
    case .waiting(let error):
        // DON'T fail here - framework retries when network returns
        self?.updateUI(.waiting)
    case .ready:
        self?.startCommunication()
    case .failed(let error):
        self?.showError(error)
    case .cancelled:
        self?.cleanup()
    @unknown default: break
    }
}

State Handling (iOS 26+)

Task {
    for await state in connection.states {
        switch state {
        case .preparing: print("Connecting...")
        case .waiting(let error): print("Waiting: \(error)")
        case .ready: await startCommunication()
        case .failed(let error): print("Failed: \(error)")
        case .cancelled: print("Cancelled")
        @unknown default: break
        }
    }
}

The Waiting State (Critical)

.waiting means network unavailable but framework retries automatically.

// WRONG - Poor UX
case .waiting:
    showError("Connection failed")

// CORRECT
case .waiting:
    showStatus("Waiting for network...")

Viability Updates

connection.viabilityUpdateHandler = { isViable in
    if !isViable {
        // Don't tear down! May recover when network returns
        showStatus("Connection interrupted...")
    }
}

Better Path Available

connection.betterPathUpdateHandler = { betterPathAvailable in
    if betterPathAvailable {
        migrateToNewConnection()
    }
}

Multipath TCP

let parameters = NWParameters.tcp
parameters.multipathServiceType = .handover  // Seamless WiFi/cellular transition

Common POSIX Errors

NWPathMonitor

let monitor = NWPathMonitor()
monitor.pathUpdateHandler = { path in
    if path.status == .satisfied {
        if path.usesInterfaceType(.wifi) { print("WiFi") }
        if path.isExpensive { print("Cellular/hotspot") }
    }
}
monitor.start(queue: .main)

Use for global UI updates, not pre-connection checks.

Getting Started with Network.framework

API Selection

Basic TLS Connection (iOS 12+)

import Network

let connection = NWConnection(
    host: NWEndpoint.Host("api.example.com"),
    port: NWEndpoint.Port(integerLiteral: 443),
    using: .tls
)

connection.stateUpdateHandler = { [weak self] state in
    switch state {
    case .ready:
        self?.sendRequest()
    case .waiting(let error):
        print("Waiting: \(error)")
    case .failed(let error):
        print("Failed: \(error)")
    default: break
    }
}

connection.start(queue: .main)

Critical: Always use [weak self] in NWConnection handlers.

Basic TLS Connection (iOS 26+)

let connection = NetworkConnection(
    to: .hostPort(host: "api.example.com", port: 443)
) {
    TLS()  // TCP and IP inferred
}

func communicate() async throws {
    try await connection.send(Data("Hello".utf8))
    let response = try await connection.receive(exactly: 100).content
}

UDP Connection

// iOS 12+
let udp = NWConnection(host: "game.example.com", port: 9000, using: .udp)

// iOS 26+
let udp = NetworkConnection(to: .hostPort(host: "game.example.com", port: 9000)) { UDP() }

Custom Parameters

let parameters = NWParameters.tls
parameters.prohibitConstrainedPaths = true  // Respect Low Data Mode
parameters.prohibitExpensivePaths = true    // Don't use cellular

Send with Pacing

connection.send(content: data, completion: .contentProcessed { [weak self] error in
    // contentProcessed = network consumed data, NOW send next chunk
    self?.sendNextChunk()
})

Receive Data

connection.receive(minimumIncompleteLength: 1, maximumLength: 65536) {
    [weak self] data, context, isComplete, error in
    if let data = data {
        self?.processData(data)
        self?.receiveMore()
    }
}

UDP Batching (30% CPU Reduction)

connection.batch {
    for frame in frames {
        connection.send(content: frame, completion: .contentProcessed { _ in })
    }
}  // 100 datagrams = ~1 syscall

Debugging

Add to Xcode scheme arguments:

-NWLoggingEnabled 1
-NWConnectionLoggingEnabled 1

iOS 26+ Structured Concurrency Networking

NetworkConnection vs NWConnection

Basic NetworkConnection

let connection = NetworkConnection(
    to: .hostPort(host: "api.example.com", port: 443)
) {
    TLS()  // TCP and IP inferred
}

func communicate() async throws {
    try await connection.send(Data("Hello".utf8))
    let response = try await connection.receive(exactly: 100).content
}

State Monitoring

Task {
    for await state in connection.states {
        switch state {
        case .preparing: print("Connecting...")
        case .waiting(let error): print("Waiting: \(error)")
        case .ready: await startCommunication()
        case .failed(let error): print("Failed: \(error)")
        case .cancelled: print("Cancelled")
        @unknown default: break
        }
    }
}

TLV Framing

TCP doesn't preserve message boundaries. TLV (Type-Length-Value) solves this:

enum GameMessage: Int {
    case character = 0
    case move = 1
}

let connection = NetworkConnection(to: endpoint) {
    TLV { TLS() }
}

// Send typed message
let data = try JSONEncoder().encode(character)
try await connection.send(data, type: GameMessage.character.rawValue)

// Receive typed message
let (data, metadata) = try await connection.receive()
switch GameMessage(rawValue: metadata.type) {
case .character: // decode character
case .move: // decode move
case .none: print("Unknown type")
}

Coder Protocol

Eliminates JSON boilerplate:

enum GameMessage: Codable {
    case character(String)
    case move(row: Int, column: Int)
}

let connection = NetworkConnection(to: endpoint) {
    Coder(GameMessage.self, using: .json) { TLS() }
}

// Send Codable directly
try await connection.send(GameMessage.character("warrior"))

// Receive Codable directly
let message = try await connection.receive().content  // Returns GameMessage!

NetworkListener

try await NetworkListener {
    Coder(GameMessage.self, using: .json) { TLS() }
}.run { connection in
    for try await (message, _) in connection.messages {
        // Handle each message
    }
}

NetworkBrowser (Wi-Fi Aware)

import WiFiAware

let endpoint = try await NetworkBrowser(
    for: .wifiAware(.connecting(to: .allPairedDevices, from: .myService))
).run { endpoints in
    .finish(endpoints.first!)
}

let connection = NetworkConnection(to: endpoint) { TLS() }

Receive Variants

try await connection.receive(exactly: 100).content
try await connection.receive(atLeast: 1, atMost: 1000).content
try await connection.receive(as: UInt32.self).content  // Network byte order

Migration from NWConnection

// Before (NWConnection)
connection.stateUpdateHandler = { [weak self] state in
    if case .ready = state { self?.sendData() }
}
func sendData() {
    connection.send(content: data, completion: .contentProcessed { [weak self] _ in
        self?.receiveData()
    })
}

// After (NetworkConnection)
Task {
    for await state in connection.states {
        if case .ready = state {
            try await connection.send(data)
            let response = try await connection.receive(exactly: 100).content
        }
    }
}

Migration Guide

API Mapping

From BSD Sockets

// WRONG - Blocks main thread
int sock = socket(AF_INET, SOCK_STREAM, 0);
connect(sock, &addr, addrlen);  // BLOCKS

// CORRECT
let connection = NWConnection(host: "example.com", port: 443, using: .tls)
connection.stateUpdateHandler = { [weak self] state in
    if case .ready = state { self?.sendData() }
}
connection.start(queue: .main)  // Non-blocking

From SCNetworkReachability

// WRONG - Race condition
if SCNetworkReachabilityGetFlags(reachability, &flags) {
    if flags.contains(.reachable) {
        connection.start()  // Network may change!
    }
}

// CORRECT - Use waiting state
connection.stateUpdateHandler = { state in
    switch state {
    case .waiting: showStatus("Waiting for network...")
    case .ready: startCommunication()
    case .failed: showError("Failed")
    default: break
    }
}

From getaddrinfo

// WRONG - Misses Happy Eyeballs, proxies
getaddrinfo("example.com", "443", &hints, &results);

// CORRECT - Framework handles DNS, IPv4/IPv6 racing
let connection = NWConnection(
    host: NWEndpoint.Host("example.com"),  // Hostname, not IP
    port: 443, using: .tls
)

From URLSession StreamTask

// Before
let task = URLSession.shared.streamTask(withHostName: "example.com", port: 443)
task.write(data, timeout: 10) { _ in }

// After (iOS 26+)
let connection = NetworkConnection(to: .hostPort(host: "example.com", port: 443)) { TLS() }
try await connection.send(data)

From NWConnection to NetworkConnection

// Before
connection.stateUpdateHandler = { [weak self] state in
    if case .ready = state { self?.sendData() }
}

// After
Task {
    for await state in connection.states {
        if case .ready = state {
            try await connection.send(data)
        }
    }
}

Migration Checklist

• [ ] Removed SCNetworkReachability
• [ ] Removed getaddrinfo / manual DNS
• [ ] Removed CFSocket / NSStream
• [ ] Using hostnames, not IPs
• [ ] Handling .waiting state
• [ ] Using [weak self] in NWConnection handlers
• [ ] Tested on real device
• [ ] Tested WiFi/cellular transitions

Troubleshooting Network.framework

Critical Anti-Patterns

1. SCNetworkReachability Before Connecting

// WRONG - Race condition
if SCNetworkReachabilityGetFlags(reachability, &flags).contains(.reachable) {
    connection.start()
}

Fix: Use .waiting state instead.

2. Blocking Socket on Main Thread

// WRONG - ANR (App Not Responding)
connect(socket, &addr, addrlen)

Fix: Use NWConnection (non-blocking).

3. Manual DNS with getaddrinfo

// WRONG - Misses Happy Eyeballs, proxies
getaddrinfo("example.com", "443", &hints, &results)

Fix: Use hostname in NWEndpoint.Host().

4. Hardcoded IP Addresses

// WRONG - Breaks proxy/VPN
let host = "192.168.1.1"

Fix: Use hostnames.

5. Ignoring Waiting State

// WRONG - Poor UX
case .waiting: showError("Failed")

Fix: Show "Waiting for network..."

6. Missing [weak self]

// WRONG - Memory leak
connection.send(content: data) { error in self.handle(error) }

Fix: Use [weak self] or NetworkConnection (iOS 26+).

Diagnostic Decision Tree

Not reaching .ready?
  Stuck in .preparing -> DNS failure (nslookup hostname)
  .waiting immediately -> No connectivity
  .failed POSIX 61 -> Connection refused (server down)
  .failed POSIX 50 -> Network interface down

TLS errors?
  -9806 -> Certificate invalid
  -9807 -> Certificate expired
  -9801 -> Protocol version

Data issues?
  Send OK, receive empty -> Framing (use TLV)
  Partial data -> Wrong byte count

Works WiFi, fails cellular?
  -> IPv6-only network, use hostname not IP

Enable Logging

-NWLoggingEnabled 1
-NWConnectionLoggingEnabled 1

Common POSIX Errors

TLS Certificate Issues

# Check certificate
openssl s_client -connect example.com:443 -showcerts
openssl s_client -connect example.com:443 | openssl x509 -noout -dates

Development only (never in production):

#if DEBUG
sec_protocol_options_set_verify_block(tlsOptions.securityProtocolOptions,
    { _, _, complete in complete(true) }, .main)
#endif

Message Framing

TCP doesn't preserve boundaries:

send("A"); send("B"); send("C")
receive() -> "ABC"  // All at once

Fix (iOS 26+): Use TLV

NetworkConnection(to: endpoint) { TLV { TLS() } }

Fix (iOS 12+): Length prefix

var length = UInt32(data.count).bigEndian
connection.send(content: Data(bytes: &length, count: 4) + data, ...)

Testing Checklist

• [ ] Real device (not simulator)
• [ ] WiFi and cellular
• [ ] Airplane Mode toggle
• [ ] WiFi to cellular transition
• [ ] IPv6-only network
• [ ] VPN active
• [ ] Weak signal

Quick Reference