swift-networking
Use when implementing Network.framework connections (NWConnection, NetworkConnection), debugging connection failures, migrating from sockets/URLSession streams, or handling network transitions. Covers UDP/TCP patterns, structured concurrency networking (iOS 26+), and common anti-patterns.
When & Why to Use This Skill
This Claude skill provides expert guidance for implementing and debugging Apple's modern Network.framework. It assists developers in managing NWConnection and NetworkConnection for high-performance TCP/UDP/QUIC protocols, handling complex network transitions, and adopting modern Swift structured concurrency (async/await) for robust iOS networking.
Use Cases
- Implementing custom low-level protocols (TCP, UDP, or QUIC) for performance-critical applications like real-time gaming or peer-to-peer communication.
- Migrating legacy networking codebases from BSD sockets, CFSocket, or URLSession streams to the modern Network.framework for better mobility handling and efficiency.
- Debugging complex connection lifecycle issues and implementing robust state handlers to manage transitions between Wi-Fi and cellular networks.
- Adopting the latest iOS 26+ networking patterns, including the Coder protocol and async/await-based NetworkConnection implementations.
- Troubleshooting TLS failures, timeouts, and common networking anti-patterns like main-thread blocking or improper error recovery.
| name | swift-networking |
|---|---|
| description | Use when implementing Network.framework connections (NWConnection, NetworkConnection), debugging connection failures, migrating from sockets/URLSession streams, or handling network transitions. Covers UDP/TCP patterns, structured concurrency networking (iOS 26+), and common anti-patterns. |
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.
Quick Reference
| Reference | Load When |
|---|---|
| Getting Started | Setting up NWConnection for TCP/UDP, choosing between APIs |
| Connection States | Handling .waiting, .ready, .failed transitions |
| iOS 26+ Networking | Using NetworkConnection with async/await, TLV framing, Coder protocol |
| Migration Guide | Moving from sockets, CFSocket, SCNetworkReachability, URLSession |
| Troubleshooting | Debugging timeouts, TLS failures, connection issues |
Core Workflow
- Choose transport (TCP/UDP/QUIC) based on use case
- Create NWConnection (iOS 12+) or NetworkConnection (iOS 26+)
- Set up state handler for connection lifecycle
- Start connection on appropriate queue
- Send/receive data with proper error handling
- 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
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.
Blocking the main thread — Never call
receive()on the main queue. Use a background DispatchQueue or Task for all network operations.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.
Not handling network transitions — WiFi/cellular switches or network loss aren't always detected automatically. Implement viability checks and state monitoring for robust apps.
Improper error recovery — Network errors need retry logic with backoff. Immediately failing on transient errors (timeouts, temporary loss) creates poor UX.