axiom-network-framework-ref

# Network.framework API Reference

## Overview

Network.framework is Apple's modern networking API that replaces Berkeley sockets, providing smart connection establishment, user-space networking, built-in TLS support, and seamless mobility. Introduced in iOS 12 (2018) with NWConnection and evolved in iOS 26 (2025) with NetworkConnection for structured concurrency.

#### Evolution timeline
- **2018 (iOS 12)** NWConnection with completion handlers, deprecates CFSocket/NSStream/SCNetworkReachability
- **2019 (iOS 13)** User-space networking (30% CPU reduction), TLS 1.3 default
- **2025 (iOS 26)** NetworkConnection with async/await, TLV framing built-in, Coder protocol, Wi-Fi Aware discovery

#### Key capabilities
- **Smart connection establishment** Happy Eyeballs (IPv4/IPv6 racing), proxy evaluation (PAC), VPN detection, WiFi Assist fallback
- **User-space networking** ~30% lower CPU usage vs sockets, memory-mapped regions, reduced context switches
- **Built-in security** TLS 1.3 by default, DTLS for UDP, certificate pinning support
- **Mobility** Automatic network transition handling (WiFi ↔ cellular), viability notifications, Multipath TCP
- **Performance** ECN (Explicit Congestion Notification), service class marking, TCP Fast Open, UDP batching

#### When to use vs URLSession
- **URLSession** HTTP, HTTPS, WebSocket, simple TCP/TLS streams → Use URLSession (optimized for these)
- **Network.framework** UDP, custom protocols, low-level control, peer-to-peer, gaming, streaming → Use Network.framework

#### Related Skills
- Use `axiom-networking` for anti-patterns, common patterns, pressure scenarios
- Use `axiom-networking-diag` for systematic troubleshooting of connection failures

---

## When to Use This Skill

Use this skill when:
- **Planning migration** from BSD sockets, CFSocket, NSStream, or SCNetworkReachability
- **Understanding API differences** between NWConnection (iOS 12-25) and NetworkConnection (iOS 26+)
- **Implementing all 12 WWDC 2025 examples** (TL