// ❌ WRONG — Race condition
if SCNetworkReachabilityGetFlags(reachability, &flags) {
    connection.start() // Network may change between check and start
}

// ❌ WRONG — Guaranteed ANR (Application Not Responding)
let socket = socket(AF_INET, SOCK_STREAM, 0)
connect(socket, &addr, addrlen) // Blocks main thread

// ❌ WRONG — Misses Happy Eyeballs, proxies, VPN
var hints = addrinfo(...)
getaddrinfo("example.com", "443", &hints, &results)
// Now manually try each address...

// ❌ WRONG — Breaks proxy/VPN compatibility
let host = "192.168.1.1" // or any IP literal

// ❌ WRONG — Poor UX
connection.stateUpdateHandler = { state in
    if case .ready = state {
        // Handle ready
    }
    // Missing: .waiting case
}

// ❌ WRONG — Memory leak
connection.send(content: data, completion: .contentProcessed { error in
    self.handleSend(error) // Retain cycle: connection → handler → self → connection
})

// ❌ WRONG — Structured concurrency violation
Task {
    let connection = NetworkConnection(...)
    connection.send(data) // async/await
    connection.stateUpdateHandler = { ... } // completion handler — don't mix
}

// ❌ WRONG — Connection fails on WiFi → cellular transition
// No viabilityUpdateHandler, no betterPathUpdateHandler
// User walks out of building → connection dies

// Step 1: Identify your use case
// Record: "UDP gaming" vs "TLS messaging" vs "Custom protocol over QUIC"
// Ask: What data am I sending? Real-time? Reliable delivery needed?

// Step 2: Check if URLSession is sufficient
// URLSession handles: HTTP, HTTPS, WebSocket, TCP/TLS streams (via StreamTask)
// Network.framework handles: UDP, custom protocols, low-level control, peer-to-peer

// If HTTP/HTTPS/WebSocket → STOP, use URLSession instead
// Example:
URLSession.shared.dataTask(with: url) { ... } // ✅ Correct for HTTP

// Step 3: Choose API version based on deployment target
if #available(iOS 26, *) {
    // Use NetworkConnection (structured concurrency, async/await)
    // TLV framing built-in, Coder protocol for Codable types
} else {
    // Use NWConnection (completion handlers)
    // Manual framing or custom framers
}

// Step 4: Verify you're NOT using deprecated APIs
// Search your codebase for these:
// - SCNetworkReachability → Use connection waiting state
// - CFSocket → Use NWConnection
// - NSStream, CFStream → Use NWConnection
// - NSNetService → Use NWBrowser or NetworkBrowser
// - getaddrinfo → Let Network.framework handle DNS

// To search:
// grep -rn "SCNetworkReachability\|CFSocket\|NSStream\|getaddrinfo" .

Need networking?
├─ HTTP, HTTPS, or WebSocket?
│  └─ YES → Use URLSession (NOT Network.framework)
│     ✅ URLSession.shared.dataTask(with: url)
│     ✅ URLSession.webSocketTask(with: url)
│     ✅ URLSession.streamTask(withHostName:port:) for TCP/TLS
│
├─ iOS 26+ and can use structured concurrency?
│  └─ YES → NetworkConnection path (async/await)
│     ├─ TCP with TLS security?
│     │  └─ Pattern 1a: NetworkConnection + TLS
│     │     Time: 10-15 minutes
│     │
│     ├─ UDP for gaming/streaming?
│     │  └─ Pattern 1b: NetworkConnection + UDP
│     │     Time: 10-15 minutes
│     │
│     ├─ Need message boundaries (framing)?
│     │  └─ Pattern 1c: TLV Framing
│     │     Type-Length-Value for mixed message types
│     │     Time: 15-20 minutes
│     │
│     └─ Send/receive Codable objects directly?
│        └─ Pattern 1d: Coder Protocol
│           No manual JSON encoding needed
│           Time: 10-15 minutes
│
└─ iOS 12-25 or need completion handlers?
   └─ YES → NWConnection path (callbacks)
      ├─ TCP with TLS security?
      │  └─ Pattern 2a: NWConnection + TLS
      │     stateUpdateHandler, completion-based send/receive
      │     Time: 15-20 minutes
      │
      ├─ UDP streaming with batching?
      │  └─ Pattern 2b: NWConnection + UDP Batch
      │     connection.batch for 30% CPU reduction
      │     Time: 10-15 minutes
      │
      ├─ Listening for incoming connections?
      │  └─ Pattern 2c: NWListener
      │     Accept inbound connections, newConnectionHandler
      │     Time: 20-25 minutes
      │
      └─ Network discovery (Bonjour)?
         └─ Pattern 2d: NWBrowser
            Discover services on local network
            Time: 25-30 minutes

// WRONG — Don't do this
var hints = addrinfo(...)
getaddrinfo("www.example.com", "1029", &hints, &results)
let sock = socket(AF_INET, SOCK_STREAM, 0)
connect(sock, results.pointee.ai_addr, results.pointee.ai_addrlen) // Blocks!

import Network

// Basic connection with TLS
let connection = NetworkConnection(
    to: .hostPort(host: "www.example.com", port: 1029)
) {
    TLS() // TCP and IP inferred automatically
}

// Send and receive with async/await
public func sendAndReceiveWithTLS() async throws {
    let outgoingData = Data("Hello, world!".utf8)
    try await connection.send(outgoingData)

    let incomingData = try await connection.receive(exactly: 98).content
    print("Received data: \(incomingData)")
}

// Optional: Monitor connection state for UI updates
Task {
    for await state in connection.states {
        switch state {
        case .preparing:
            print("Establishing connection...")
        case .ready:
            print("Connected!")
        case .waiting(let error):
            print("Waiting for network: \(error)")
        case .failed(let error):
            print("Connection failed: \(error)")
        case .cancelled:
            print("Connection cancelled")
        @unknown default:
            break
        }
    }
}

let connection = NetworkConnection(
    to: .hostPort(host: "www.example.com", port: 1029),
    using: .parameters {
        TLS {
            TCP {
                IP()
                    .fragmentationEnabled(false)
            }
        }
    }
    .constrainedPathsProhibited(true) // Don't use cellular in low data mode
)

// WRONG — Don't do this
let sock = socket(AF_INET, SOCK_DGRAM, 0)
let sent = sendto(sock, buffer, length, 0, &addr, addrlen)
// Blocks, no batching, axiom-high CPU overhead

import Network

// UDP connection for real-time data
let connection = NetworkConnection(
    to: .hostPort(host: "game-server.example.com", port: 9000)
) {
    UDP()
}

// Send game state update
public func sendGameUpdate() async throws {
    let gameState = Data("player_position:100,50".utf8)
    try await connection.send(gameState)
}

// Receive game updates
public func receiveGameUpdates() async throws {
    while true {
        let (data, _) = try await connection.receive()
        processGameState(data)
    }
}

// Batch multiple datagrams for efficiency (30% CPU reduction)
public func sendMultipleUpdates(_ updates: [Data]) async throws {
    for update in updates {
        try await connection.send(update)
    }
}

// WRONG — Error-prone, boilerplate-heavy
let lengthData = try await connection.receive(exactly: 4).content
let length = lengthData.withUnsafeBytes { $0.load(as: UInt32.self) }
let messageData = try await connection.receive(exactly: Int(length)).content
// Now decode manually...

import Network

// Define your message types
enum GameMessage: Int {
    case selectedCharacter = 0
    case move = 1
}

struct GameCharacter: Codable {
    let character: String
}

struct GameMove: Codable {
    let row: Int
    let column: Int
}

// Connection with TLV framing
let connection = NetworkConnection(
    to: .hostPort(host: "www.example.com", port: 1029)
) {
    TLV {
        TLS()
    }
}

// Send typed messages
public func sendWithTLV() async throws {
    let characterData = try JSONEncoder().encode(GameCharacter(character: "🐨"))
    try await connection.send(characterData, type: GameMessage.selectedCharacter.rawValue)
}

// Receive typed messages
public func receiveWithTLV() async throws {
    let (incomingData, metadata) = try await connection.receive()

    switch GameMessage(rawValue: metadata.type) {
    case .selectedCharacter:
        let character = try JSONDecoder().decode(GameCharacter.self, from: incomingData)
        print("Character selected: \(character)")
    case .move:
        let move = try JSONDecoder().decode(GameMove.self, from: incomingData)
        print("Move: row=\(move.row), column=\(move.column)")
    case .none:
        print("Unknown message type: \(metadata.type)")
    }
}

// WRONG — Boilerplate-heavy, error-prone
let encoder = JSONEncoder()
let data = try encoder.encode(message)
try await connection.send(data)

let receivedData = try await connection.receive().content
let decoder = JSONDecoder()
let message = try decoder.decode(GameMessage.self, from: receivedData)

import Network

// Define message types as Codable enum
enum GameMessage: Codable {
    case selectedCharacter(String)
    case move(row: Int, column: Int)
}

// Connection with Coder protocol
let connection = NetworkConnection(
    to: .hostPort(host: "www.example.com", port: 1029)
) {
    Coder(GameMessage.self, using: .json) {
        TLS()
    }
}

// Send Codable types directly
public func sendWithCoder() async throws {
    let selectedCharacter: GameMessage = .selectedCharacter("🐨")
    try await connection.send(selectedCharacter) // No encoding needed!
}

// Receive Codable types directly
public func receiveWithCoder() async throws {
    let gameMessage = try await connection.receive().content // Returns GameMessage!

    switch gameMessage {
    case .selectedCharacter(let character):
        print("Character selected: \(character)")
    case .move(let row, let column):
        print("Move: (\(row), \(column))")
    }
}

// ❌ NEVER check reachability before connecting
/*
if SCNetworkReachabilityGetFlags(reachability, &flags) {
    if flags.contains(.reachable) {
        connection.start()
    } else {
        showError("No network") // RACE CONDITION
    }
}
*/

// ✅ ALWAYS let Network.framework handle waiting state
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 .preparing:
        // Show: "Connecting..."
        self?.showStatus("Connecting...")

    case .ready:
        // Connection established
        self?.hideStatus()
        self?.sendRequest()

    case .waiting(let error):
        // CRITICAL: Don't fail here, show "Waiting for network"
        // Network.framework will automatically retry when network returns
        print("Waiting for network: \(error)")
        self?.showStatus("Waiting for network...")
        // User walks out of elevator → WiFi returns → automatic retry

    case .failed(let error):
        // Only fail after framework exhausts all options
        // (tried IPv4, IPv6, proxies, WiFi Assist, waited for network)
        print("Connection failed: \(error)")
        self?.showError("Connection failed. Please check your network.")

    case .cancelled:
        self?.hideStatus()

    @unknown default:
        break
    }
}

connection.start(queue: .main)

// ❌ NEVER call blocking socket APIs on main thread
/*
let sock = socket(AF_INET, SOCK_STREAM, 0)
connect(sock, &addr, addrlen) // BLOCKS MAIN THREAD → ANR
*/

// ✅ ALWAYS use async connection, even for localhost
func connectToLocalhost() {
    let connection = NWConnection(
        host: "127.0.0.1",
        port: 8080,
        using: .tcp
    )

    connection.stateUpdateHandler = { [weak self] state in
        switch state {
        case .ready:
            print("Connected to localhost")
            self?.sendRequest(on: connection)
        case .failed(let error):
            print("Localhost connection failed: \(error)")
        default:
            break
        }
    }

    // Non-blocking, returns immediately
    connection.start(queue: .main)
}

// Move blocking call to background queue (minimum viable fix)
DispatchQueue.global(qos: .userInitiated).async {
    let sock = socket(AF_INET, SOCK_STREAM, 0)
    connect(sock, &addr, addrlen) // Still blocks, but not main thread

    DispatchQueue.main.async {
        // Update UI after connection
    }
}

// ❌ WRONG for real-time gaming
/*
let webSocket = URLSession.shared.webSocketTask(with: url)
webSocket.resume()
webSocket.send(.data(positionUpdate)) { error in
    // TCP guarantees delivery but blocks on loss
    // Old position blocks new position → stutter
}
*/

// ✅ CORRECT for real-time gaming
let connection = NWConnection(
    host: NWEndpoint.Host("game-server.example.com"),
    port: NWEndpoint.Port(integerLiteral: 9000),
    using: .udp
)

connection.stateUpdateHandler = { state in
    if case .ready = state {
        print("Ready to send game updates")
    }
}

connection.start(queue: .main)

// Send player position updates (20/second)
func sendPosition(_ position: PlayerPosition) {
    let data = encodePosition(position)
    connection.send(content: data, completion: .contentProcessed { error in
        // Fire and forget, no blocking
        // If this frame is lost, next frame (50ms later) makes it obsolete
    })
}