Skip to content

dpearson2699/swift-ios-skills / skills/ios-networking

ios-networking

Verified

Build, review, or improve networking code in iOS/macOS apps using URLSession with async/await, structured concurrency, and modern Swift patterns. Use when working with REST APIs, downloading files, uploading data, WebSocket connections, pagination, retry logic, request middleware, caching, background transfers, or network reachability monitoring. Also use when handling HTTP requests, API clients, network error handling, or data fetching in Swift apps.

references/network-framework.md

View on GitHub
# Network.framework

Low-level networking with the Network framework. Use when you need TCP/UDP
connections, WebSockets, Bonjour service discovery, local servers, or network
path monitoring beyond what URLSession provides. All examples target
Swift 6.3 / iOS 26+.

## Contents

- [NWConnection](#nwconnection)
- [NWListener](#nwlistener)
- [NWBrowser](#nwbrowser)
- [NWPathMonitor](#nwpathmonitor)
- [NWParameters Configuration](#nwparameters-configuration)
- [TLS Configuration](#tls-configuration)
- [WebSocket Support](#websocket-support)
- [NetworkConnection (iOS 26+)](#networkconnection-ios-26)

## NWConnection

A bidirectional data connection between a local and remote endpoint. Supports
TCP, UDP, TLS, DTLS, QUIC, and WebSocket protocols.

**Documentation:**
[sosumi.ai/documentation/network/nwconnection](https://sosumi.ai/documentation/network/nwconnection)

### TCP Connection

```swift
import Network

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

connection.stateUpdateHandler = { state in
    switch state {
    case .ready:
        print("Connected")
    case .waiting(let error):
        print("Waiting: \(error.localizedDescription)")
    case .failed(let error):
        print("Failed: \(error.localizedDescription)")
    case .cancelled:
        print("Cancelled")
    default:
        break
    }
}

connection.start(queue: .main)
```

### Sending Data

```swift
func send(_ data: Data, on connection: NWConnection) {
    connection.send(
        content: data,
        contentContext: .defaultMessage,
        isComplete: true,
        completion: .contentProcessed { error in
            if let error {
                print("Send error: \(error)")
            }
        }
    )
}
```

### Receiving Data

```swift
func receive(on connection: NWConnection) {
    connection.receive(
        minimumIncompleteLength: 1,
        maximumLength: 65536
    ) { content, contentContext, isComplete, error in
        if let data = content {
            handleData(data)
        }
        if isComplete {
            connection.cancel()
        } else if let error {
            print("Receive error: \(error)")
        } else {
            // Continue receiving
            receive(on: connection)
        }
    }
}
```

### UDP Connection

```swift
let udpConnection = NWConnection(
    host: "239.0.0.1",
    port: 5000,
    using: .udp
)

udpConnection.stateUpdateHandler = { state in
    if case .ready = state {
        let message = "Hello".data(using: .utf8)!
        udpConnection.send(
            content: message,
            completion: .contentProcessed { _ in }
        )
    }
}

udpConnection.start(queue: .main)
```

### Connection Lifecycle

States flow in order: `setup` → `preparing` → `ready` → `cancelled`/`failed`.
A connection may enter `waiting(NWError)` if the network path is unavailable
and retry when connectivity returns.

Always cancel connections when done:

```swift
connection.cancel()  // Releases resources, transitions to .cancelled
```

## NWListener

An object that listens for incoming network connections. Use to create local
TCP/UDP servers.

**Documentation:**
[sosumi.ai/documentation/network/nwlistener](https://sosumi.ai/documentation/network/nwlistener)

### TCP Server

```swift
import Network

func startServer(port: UInt16) throws -> NWListener {
    let listener = try NWListener(using: .tcp, on: NWEndpoint.Port(rawValue: port)!)

    listener.stateUpdateHandler = { state in
        switch state {
        case .ready:
            print("Listening on port \(listener.port?.rawValue ?? 0)")
        case .failed(let error):
            print("Listener failed: \(error)")
            listener.cancel()
        default:
            break
        }
    }

    listener.newConnectionHandler = { connection in
        print("New connection from \(connection.endpoint)")
        connection.stateUpdateHandler = { state in
            if case .ready = state {
                receive(on: connection)
            }
        }
        connection.start(queue: .main)
    }

    listener.start(queue: .main)
    return listener
}
```

### Advertising via Bonjour

```swift
let listener = try NWListener(using: .tcp)
listener.service = NWListener.Service(
    name: "MyApp",
    type: "_myapp._tcp"
)
listener.serviceRegistrationUpdateHandler = { change in
    switch change {
    case .add(let endpoint):
        print("Service registered: \(endpoint)")
    default:
        break
    }
}
listener.start(queue: .main)
```

## NWBrowser

Discovers Bonjour/mDNS services on the local network.

**Documentation:**
[sosumi.ai/documentation/network/nwbrowser](https://sosumi.ai/documentation/network/nwbrowser)

### Service Discovery

```swift
import Network

let browser = NWBrowser(
    for: .bonjour(type: "_myapp._tcp", domain: nil),
    using: .tcp
)

browser.stateUpdateHandler = { state in
    if case .failed(let error) = state {
        print("Browser failed: \(error)")
    }
}

browser.browseResultsChangedHandler = { results, changes in
    for result in results {
        switch result.endpoint {
        case .service(let name, let type, let domain, _):
            print("Found: \(name).\(type)\(domain)")
        default:
            break
        }
    }

    for change in changes {
        switch change {
        case .added(let result):
            print("Added: \(result.endpoint)")
        case .removed(let result):
            print("Removed: \(result.endpoint)")
        default:
            break
        }
    }
}

browser.start(queue: .main)
```

### Connecting to a Discovered Service

```swift
// result is an NWBrowser.Result from browseResultsChangedHandler
let connection = NWConnection(to: result.endpoint, using: .tcp)
connection.start(queue: .main)
```

## NWPathMonitor

Monitors network path changes. Replaces the deprecated `SCNetworkReachability`
API. Use to detect connectivity changes, expensive paths (cellular), and
constrained paths (Low Data Mode).

**Documentation:**
[sosumi.ai/documentation/network/nwpathmonitor](https://sosumi.ai/documentation/network/nwpathmonitor)

### Basic Reachability with AsyncSequence

```swift
import Network

@MainActor @Observable
class ConnectivityModel {
    var isConnected = true
    var isExpensive = false
    var isConstrained = false

    func startMonitoring() async {
        let monitor = NWPathMonitor()

        for await path in monitor {
            isConnected = path.status == .satisfied
            isExpensive = path.isExpensive       // Cellular
            isConstrained = path.isConstrained   // Low Data Mode
        }
    }
}
```

### Monitor Specific Interface

```swift
// Monitor only Wi-Fi
let wifiMonitor = NWPathMonitor(requiredInterfaceType: .wifi)
wifiMonitor.pathUpdateHandler = { path in
    print("Wi-Fi: \(path.status)")
}
wifiMonitor.start(queue: .global())
```

### Key NWPath Properties

| Property | Description |
|---|---|
| `status` | `.satisfied`, `.unsatisfied`, or `.requiresConnection` |
| `isExpensive` | `true` on cellular or personal hotspot |
| `isConstrained` | `true` when Low Data Mode is enabled |
| `availableInterfaces` | Array of available `NWInterface` objects |
| `supportsDNS` | Whether DNS resolution is available |
| `supportsIPv4` / `supportsIPv6` | Protocol family support |

### Adapting Behavior

```swift
let monitor = NWPathMonitor()

for await path in monitor {
    if path.isConstrained {
        // Low Data Mode: reduce image quality, skip prefetch
        imageQuality = .low
    } else if path.isExpensive {
        // Cellular: use standard quality, skip video preload
        imageQuality = .standard
    } else {
        // Wi-Fi: full quality, prefetch aggressively
        imageQuality = .high
    }
}
```

## NWParameters Configuration

`NWParameters` defines the protocols and options for connections and listeners.

```swift
import Network

// TCP with custom options
let tcpParams = NWParameters.tcp
tcpParams.requiredInterfaceType = .wifi
tcpParams.prohibitExpensivePaths = true
tcpParams.prohibitConstrainedPaths = true

let tcpOptions = tcpParams.defaultProtocolStack
    .transportProtocol as! NWProtocolTCP.Options
tcpOptions.connectionTimeout = 10
tcpOptions.enableKeepalive = true
tcpOptions.keepaliveInterval = 30

let connection = NWConnection(
    host: "api.example.com",
    port: 8080,
    using: tcpParams
)
```

### UDP Parameters

```swift
let udpParams = NWParameters.udp
let udpOptions = udpParams.defaultProtocolStack
    .transportProtocol as! NWProtocolUDP.Options
udpOptions.preferNoChecksum = true

let connection = NWConnection(
    host: "239.0.0.1",
    port: 5000,
    using: udpParams
)
```

## TLS Configuration

Configure TLS for secure connections using `NWProtocolTLS.Options`.
Network.framework operates below the URL Loading System, so ATS does not
automatically enforce URLSession-style policy here. When you use
Network.framework for a secure protocol, configure TLS parameters and trust
handling for that protocol stack; keep deep certificate-trust and SPKI pinning
implementation in `swift-security`.

```swift
import Network

let tlsParams = NWParameters(tls: NWProtocolTLS.Options())

// Access TLS options for customization
let tlsOptions = tlsParams.defaultProtocolStack
    .applicationProtocols.first as! NWProtocolTLS.Options

sec_protocol_options_set_min_tls_protocol_version(
    tlsOptions.securityProtocolOptions,
    .TLSv13
)

let connection = NWConnection(
    host: "secure.example.com",
    port: 443,
    using: tlsParams
)
```

### Inspecting TLS Metadata

```swift
connection.stateUpdateHandler = { state in
    if case .ready = state {
        if let metadata = connection.metadata(
            definition: NWProtocolTLS.definition
        ) as? NWProtocolTLS.Metadata {
            let secMetadata = metadata.securityProtocolMetadata
            let negotiatedProtocol = sec_protocol_metadata_get_negotiated_tls_protocol_version(secMetadata)
            print("TLS version: \(negotiatedProtocol)")
        }
    }
}
```

## WebSocket Support

Network.framework supports WebSocket via `NWProtocolWebSocket`.

### WebSocket Client

```swift
import Network

func createWebSocketConnection(url: String) -> NWConnection {
    let wsOptions = NWProtocolWebSocket.Options()
    wsOptions.autoReplyPing = true

    let params = NWParameters.tls
    params.defaultProtocolStack.applicationProtocols.insert(
        wsOptions, at: 0
    )

    let connection = NWConnection(
        host: NWEndpoint.Host(url),
        port: 443,
        using: params
    )

    return connection
}
```

### Sending WebSocket Messages

```swift
func sendWebSocketMessage(_ text: String, on connection: NWConnection) {
    let metadata = NWProtocolWebSocket.Metadata(opcode: .text)
    let context = NWConnection.ContentContext(
        identifier: "textMessage",
        metadata: [metadata]
    )

    let data = text.data(using: .utf8)
    connection.send(
        content: data,
        contentContext: context,
        isComplete: true,
        completion: .contentProcessed { error in
            if let error {
                print("WebSocket send error: \(error)")
            }
        }
    )
}
```

### Receiving WebSocket Messages

```swift
func receiveWebSocketMessage(on connection: NWConnection) {
    connection.receiveMessage { data, context, isComplete, error in
        if let data,
           let metadata = context?.protocolMetadata(
               definition: NWProtocolWebSocket.definition
           ) as? NWProtocolWebSocket.Metadata {
            switch metadata.opcode {
            case .text:
                let text = String(data: data, encoding: .utf8) ?? ""
                print("Received text: \(text)")
            case .binary:
                print("Received binary: \(data.count) bytes")
            case .close:
                print("Connection closed")
                return
            default:
                break
            }
        }
        // Continue receiving
        receiveWebSocketMessage(on: connection)
    }
}
```

## NetworkConnection (iOS 26+)

`NetworkConnection` is a new Swift-native API introduced in iOS 26 that
provides a modern, type-safe alternative to `NWConnection`. It uses generics
over protocol stacks, supports structured concurrency patterns, and integrates
with async/await via closure-based state handlers.

**Documentation:**
[sosumi.ai/documentation/network/networkconnection](https://sosumi.ai/documentation/network/networkconnection)

### Key Differences from NWConnection

| | `NWConnection` | `NetworkConnection` |
|---|---|---|
| **Availability** | iOS 12+ | iOS 26+ |
| **Type safety** | Untyped protocol stack | Generic `ApplicationProtocol` parameter |
| **Streams** | Single connection | Built-in QUIC stream multiplexing |
| **State updates** | `stateUpdateHandler` callback | `onStateUpdate`, `onPathUpdate` closures |
| **Wi-Fi Aware** | Not supported | `wifiAware` property |
| **API style** | Callback-based | Closure-based with `Sendable` support |

### Basic Usage Shape

```swift
import Network

let endpoint = NWEndpoint.hostPort(host: "api.example.com", port: 443)
```

Use the initializer variant that matches your protocol stack. The documented
forms are:

```swift
// Protocol-stack builder form.
NetworkConnection(to: endpoint) {
    // ProtocolStackBuilder<ApplicationProtocol>
}

// Parameters-builder form.
NetworkConnection(to: endpoint, using: builder)
```

After constructing a concrete connection for your app's protocol stack, install
state handlers and start it:

```swift
func startConnection<ApplicationProtocol>(
    _ connection: NetworkConnection<ApplicationProtocol>
) where ApplicationProtocol: NetworkProtocolOptions {
    connection.onStateUpdate { state in
        switch state {
        case .ready:
            print("Connected")
        case .failed(let error):
            print("Failed: \(error)")
        case .cancelled:
            print("Cancelled")
        default:
            break
        }
    }

    connection.start()
}
```

`NetworkConnection` is for lower-level protocol stacks and QUIC-style transport
work. Keep ordinary HTTP APIs on `URLSession` unless you need capabilities that
the URL Loading System does not provide.

### QUIC Multiplexed Streams

`NetworkConnection<QUIC>` supports QUIC stream multiplexing natively.
Opening and accepting streams are asynchronous and throwing operations.

```swift
func openBidirectionalStream(
    on connection: NetworkConnection<QUIC>
) async throws -> QUIC.Stream<QUICStream> {
    try await connection.openStream(directionality: .bidirectional)
}

func handleInboundStreams(
    on connection: NetworkConnection<QUIC>
) async throws {
    try await connection.inboundStreams { stream in
        // Process each incoming QUIC stream.
    }
}
```

### Migration Guidance

For new iOS 26+ low-level networking work, evaluate `NetworkConnection` before
adding new `NWConnection` code:
- It provides stronger type safety through its generic `ApplicationProtocol`.
- Stream multiplexing is a first-class concept for QUIC.
- The API is designed for modern Swift with `Sendable` conformance.

For projects supporting iOS versions before 26, continue using `NWConnection`.
Both APIs coexist and `NWConnection` is not deprecated.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall