dpearson2699/swift-ios-skills / skills/ios-networking
ios-networking
VerifiedBuild, 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.4 KB |
| evals/evals.json | config | 4.4 KB |
| references/background-websocket.md | markdown | 27.0 KB |
| references/file-storage-patterns.md | markdown | 11.3 KB |
| references/lightweight-clients.md | markdown | 2.6 KB |
| references/network-framework.md | markdown | 15.0 KB |
| references/urlsession-patterns.md | markdown | 31.2 KB |
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |