🌐 Network Framework

⭐ Difficulty: ⭐⭐⭐ ⏱️ Est. Time: 2-3h 📂 System & Network

현대적인 저수준 네트워크 통신 프레임워크

iOS 12+TLS 1.3 Supported

✨ Network Framework?

Network is a modern low-level framework for implementing network communication using TCP, UDP, TLS, WebSocket and more. It provides finer control than URLSession, using NWConnection and NWListener for client/server communication. It offers advanced features like Bonjour service discovery, IPv6 support, and network path monitoring.

💡 Key Features: TCP/UDP Communication · TLS 1.3 Encryption · WebSocket Support · Bonjour Discovery · Network Path Monitoring · IPv4/IPv6 · Custom Protocols

🔌 1. NWConnection — TCP Client

TCP 연결을 생성하고 데이터를 주고받.

TCPClient.swift — TCP 클라이언트

import Network
import SwiftUI

@Observable
class TCPClient {
    private var connection: NWConnection?
    var isConnected = false
    var receivedMessages: [String] = []

    // TCP 연결 시작
    func connect(to host: String, port: UInt16) {
        // 호스트와 포트 설정
        guard let endpoint = NWEndpoint.Host(host) else {
            print("❌ 잘못된 호스트")
            return
        }

        let port = NWEndpoint.Port(rawValue: port) ?? NWEndpoint.Port.any

        // TCP 파라미터
        let parameters = NWParameters.tcp

        // TLS 활성화 (HTTPS)
        parameters.includeTLS = true

        // IPv4/IPv6 우선순위
        parameters.preferNoProxies = true
        parameters.requiredInterfaceType = .wifi // .wifi, .cellular, .loopback

        // 연결 생성
        connection = NWConnection(host: endpoint, port: port, using: parameters)

        // 상태 핸들러
        connection?.stateUpdateHandler = { [weak self] state in
            switch state {
            case .ready:
                print("✅ 연결 성공")
                self?.isConnected = true
                self?.receiveMessage()

            case .waiting(let error):
                print("⏳ 연결 대기 중: \(error)")

            case .failed(let error):
                print("❌ 연결 실패: \(error)")
                self?.isConnected = false

            case .cancelled:
                print("❌ 연결 취소됨")
                self?.isConnected = false

            default:
                break
            }
        }

        // 연결 시작
        connection?.start(queue: .global(qos: .userInitiated))
        print("🔗 연결 시도: \(host):\(port)")
    }

    // 메시지 전송
    func sendMessage(_ message: String) {
        guard let connection = connection, isConnected else {
            print("⚠️ 연결되지 않음")
            return
        }

        guard let data = message.data(using: .utf8) else { return }

        connection.send(
            content: data,
            completion: .contentProcessed { error in
                if let error = error {
                    print("❌ 전송 실패: \(error)")
                } else {
                    print("📤 전송 완료: \(message)")
                }
            }
        )
    }

    // 메시지 수신
    private func receiveMessage() {
        connection?.receive(minimumIncompleteLength: 1, maximumLength: 65536) { [weak self] data, context, isComplete, error in
            if let error = error {
                print("❌ 수신 에러: \(error)")
                return
            }

            if let data = data, !data.isEmpty {
                if let message = String(data: data, encoding: .utf8) {
                    print("📥 수신: \(message)")
                    self?.receivedMessages.append(message)
                }
            }

            // 계속 수신 대기
            if !isComplete {
                self?.receiveMessage()
            }
        }
    }

    // 연결 종료
    func disconnect() {
        connection?.cancel()
        connection = nil
        isConnected = false
        print("❌ 연결 종료")
    }
}

🎧 2. NWListener - TCP 서버

TCP 서버를 만들어 클라이언트 연결을 수신.

TCPServer.swift — TCP 서버

import Network

@Observable
class TCPServer {
    private var listener: NWListener?
    private var connections: [NWConnection] = []
    var isListening = false
    var port: UInt16 = 0

    // 서버 시작
    func startServer(on port: UInt16) {
        do {
            // TCP 파라미터
            let parameters = NWParameters.tcp
            parameters.acceptLocalOnly = true // 로컬 연결만 허용

            // 리스너 생성
            let nwPort = NWEndpoint.Port(rawValue: port) ?? NWEndpoint.Port.any
            listener = try NWListener(using: parameters, on: nwPort)

            // 상태 핸들러
            listener?.stateUpdateHandler = { [weak self] state in
                switch state {
                case .ready:
                    print("✅ 서버 시작됨")
                    self?.isListening = true
                    if let port = self?.listener?.port {
                        self?.port = port.rawValue
                        print("  포트: \(port)")
                    }

                case .failed(let error):
                    print("❌ 서버 실패: \(error)")
                    self?.isListening = false

                case .cancelled:
                    print("❌ 서버 취소됨")
                    self?.isListening = false

                default:
                    break
                }
            }

            // 새 연결 핸들러
            listener?.newConnectionHandler = { [weak self] newConnection in
                print("🔗 새 클라이언트 연결")
                self?.handleConnection(newConnection)
            }

            // 리스너 시작
            listener?.start(queue: .global(qos: .userInitiated))

        } catch {
            print("❌ 서버 시작 실패: \(error)")
        }
    }

    // 클라이언트 연결 처리
    private func handleConnection(_ connection: NWConnection) {
        connections.append(connection)

        // 상태 핸들러
        connection.stateUpdateHandler = { state in
            switch state {
            case .ready:
                print("  ✅ 클라이언트 준비됨")
                self.receiveMessage(from: connection)

            case .failed(let error):
                print("  ❌ 클라이언트 실패: \(error)")
                self.removeConnection(connection)

            case .cancelled:
                print("  ❌ 클라이언트 연결 해제")
                self.removeConnection(connection)

            default:
                break
            }
        }

        connection.start(queue: .global(qos: .userInitiated))
    }

    // 메시지 수신
    private func receiveMessage(from connection: NWConnection) {
        connection.receive(minimumIncompleteLength: 1, maximumLength: 65536) { data, context, isComplete, error in
            if let error = error {
                print("  ❌ 수신 에러: \(error)")
                return
            }

            if let data = data, !data.isEmpty {
                if let message = String(data: data, encoding: .utf8) {
                    print("  📥 수신: \(message)")

                    // Echo 응답
                    let response = "Echo: \(message)"
                    self.sendMessage(response, to: connection)
                }
            }

            if !isComplete {
                self.receiveMessage(from: connection)
            }
        }
    }

    // 메시지 전송
    private func sendMessage(_ message: String, to connection: NWConnection) {
        guard let data = message.data(using: .utf8) else { return }

        connection.send(content: data, completion: .contentProcessed { error in
            if let error = error {
                print("  ❌ 전송 실패: \(error)")
            } else {
                print("  📤 전송: \(message)")
            }
        })
    }

    // 연결 제거
    private func removeConnection(_ connection: NWConnection) {
        connections.removeAll { $0 === connection }
    }

    // 서버 중지
    func stopServer() {
        listener?.cancel()
        listener = nil

        connections.forEach { $0.cancel() }
        connections.removeAll()

        isListening = false
        print("⏹️ 서버 중지")
    }
}

📡 3. UDP 통신

UDP 프로토콜로 데이터그램을 주고받.

UDPClient.swift — UDP 클라이언트

import Network

@Observable
class UDPClient {
    private var connection: NWConnection?
    var isConnected = false

    // UDP 연결
    func connect(to host: String, port: UInt16) {
        guard let endpoint = NWEndpoint.Host(host) else { return }
        let port = NWEndpoint.Port(rawValue: port) ?? NWEndpoint.Port.any

        // UDP 파라미터
        let parameters = NWParameters.udp

        connection = NWConnection(host: endpoint, port: port, using: parameters)

        connection?.stateUpdateHandler = { [weak self] state in
            switch state {
            case .ready:
                print("✅ UDP 준비됨")
                self?.isConnected = true

            case .failed(let error):
                print("❌ UDP 실패: \(error)")
                self?.isConnected = false

            default:
                break
            }
        }

        connection?.start(queue: .global(qos: .userInitiated))
        print("📡 UDP 연결: \(host):\(port)")
    }

    // 데이터그램 전송
    func sendDatagram(_ message: String) {
        guard let connection = connection, isConnected else { return }
        guard let data = message.data(using: .utf8) else { return }

        connection.send(content: data, completion: .contentProcessed { error in
            if let error = error {
                print("❌ UDP 전송 실패: \(error)")
            } else {
                print("📤 UDP 전송: \(message)")
            }
        })
    }

    // 데이터그램 수신
    func receiveDatagram() {
        connection?.receiveMessage { data, context, isComplete, error in
            if let error = error {
                print("❌ UDP 수신 에러: \(error)")
                return
            }

            if let data = data, let message = String(data: data, encoding: .utf8) {
                print("📥 UDP 수신: \(message)")
            }

            // 계속 수신
            self.receiveDatagram()
        }
    }

    // 연결 종료
    func disconnect() {
        connection?.cancel()
        connection = nil
        isConnected = false
    }
}

🔍 4. Bonjour 서비스 검색

로컬 네트워크에서 Bonjour 서비스를 검색.

BonjourBrowser.swift — Bonjour Discovery

import Network

@Observable
class BonjourBrowser {
    private var browser: NWBrowser?
    var discoveredServices: [NWBrowser.Result] = []
    var isBrowsing = false

    // Bonjour 검색 시작
    func startBrowsing(serviceType: String = "_http._tcp", domain: String = "local.") {
        // Browser 파라미터
        let parameters = NWParameters()
        parameters.includePeerToPeer = true

        // Bonjour 서비스 타입
        let bonjourType = NWBrowser.Descriptor.bonjour(type: serviceType, domain: domain)

        // Browser 생성
        browser = NWBrowser(for: bonjourType, using: parameters)

        // 상태 핸들러
        browser?.stateUpdateHandler = { [weak self] state in
            switch state {
            case .ready:
                print("✅ Bonjour 검색 시작")
                self?.isBrowsing = true

            case .failed(let error):
                print("❌ 검색 실패: \(error)")
                self?.isBrowsing = false

            case .cancelled:
                print("❌ 검색 취소됨")
                self?.isBrowsing = false

            default:
                break
            }
        }

        // 검색 결과 핸들러
        browser?.browseResultsChangedHandler = { [weak self] results, changes in
            print("🔍 서비스 변경: \(changes.count)개")

            for change in changes {
                switch change {
                case .added(let result):
                    print("  ➕ 서비스 발견: \(result.endpoint)")
                    self?.discoveredServices.append(result)

                case .removed(let result):
                    print("  ➖ 서비스 사라짐: \(result.endpoint)")
                    self?.discoveredServices.removeAll { $0.endpoint == result.endpoint }

                case .changed(old: let old, new: let new, flags: _):
                    print("  🔄 서비스 변경: \(old.endpoint) -> \(new.endpoint)")

                case .identical:
                    break

                @unknown default:
                    break
                }
            }
        }

        // 검색 시작
        browser?.start(queue: .global(qos: .userInitiated))
    }

    // 검색 중지
    func stopBrowsing() {
        browser?.cancel()
        browser = nil
        isBrowsing = false
        discoveredServices.removeAll()
        print("⏹️ 검색 중지")
    }
}

📊 5. 네트워크 경로 모니터링

네트워크 상태와 경로 변화를 감지.

NetworkMonitor.swift — Network Monitoring

import Network

@Observable
class NetworkMonitor {
    private let monitor = NWPathMonitor()
    var isConnected = false
    var connectionType: NWInterface.InterfaceType?
    var isExpensive = false
    var isConstrained = false

    init() {
        startMonitoring()
    }

    // 모니터링 시작
    func startMonitoring() {
        monitor.pathUpdateHandler = { [weak self] path in
            self?.isConnected = path.status == .satisfied
            self?.isExpensive = path.isExpensive
            self?.isConstrained = path.isConstrained

            // 연결 타입 확인
            if path.usesInterfaceType(.wifi) {
                self?.connectionType = .wifi
                print("📡 Wi-Fi 연결")
            } else if path.usesInterfaceType(.cellular) {
                self?.connectionType = .cellular
                print("📱 셀룰러 연결")
            } else if path.usesInterfaceType(.wiredEthernet) {
                self?.connectionType = .wiredEthernet
                print("🔌 유선 이더넷 연결")
            } else {
                self?.connectionType = nil
                print("❌ 연결 없음")
            }

            // 연결 상태
            switch path.status {
            case .satisfied:
                print("✅ 네트워크 연결됨")
            case .unsatisfied:
                print("❌ 네트워크 연결 안 됨")
            case .requiresConnection:
                print("⏳ 연결 필요")
            @unknown default:
                break
            }

            // 비용 정보
            if path.isExpensive {
                print("💰 비용이 발생하는 네트워크 (셀룰러 데이터)")
            }

            if path.isConstrained {
                print("⚠️ 제한된 네트워크 (저전력 모드)")
            }

            // 사용 가능한 인터페이스
            print("  사용 가능한 인터페이스:")
            for interface in path.availableInterfaces {
                print("    - \(interface.type): \(interface.name)")
            }
        }

        monitor.start(queue: .global(qos: .userInitiated))
    }

    // 모니터링 중지
    func stopMonitoring() {
        monitor.cancel()
    }

    deinit {
        stopMonitoring()
    }
}

📱 6. SwiftUI Integration

네트워크 모니터링 UI implementation.

NetworkMonitorView.swift — Network Status UI

import SwiftUI

struct NetworkMonitorView: View {
    @State private var networkMonitor = NetworkMonitor()

    var body: some View {
        NavigationStack {
            Form {
                Section("연결 상태") {
                    HStack {
                        Circle()
                            .fill(networkMonitor.isConnected ? Color.green : Color.red)
                            .frame(width: 16, height: 16)

                        Text(networkMonitor.isConnected ? "연결됨" : "연결 안 됨")
                            .font(.headline)
                    }

                    if let type = networkMonitor.connectionType {
                        HStack {
                            Text("연결 타입")
                            Spacer()
                            Text(connectionTypeString(type))
                                .foregroundStyle(.secondary)
                        }
                    }
                }

                Section("네트워크 특성") {
                    HStack {
                        Image(systemName: networkMonitor.isExpensive ? "checkmark.circle.fill" : "xmark.circle")
                            .foregroundStyle(networkMonitor.isExpensive ? .orange : .secondary)
                        Text("비용 발생")
                        Spacer()
                        Text(networkMonitor.isExpensive ? "예" : "아니오")
                            .foregroundStyle(.secondary)
                    }

                    HStack {
                        Image(systemName: networkMonitor.isConstrained ? "checkmark.circle.fill" : "xmark.circle")
                            .foregroundStyle(networkMonitor.isConstrained ? .orange : .secondary)
                        Text("제한됨")
                        Spacer()
                        Text(networkMonitor.isConstrained ? "예" : "아니오")
                            .foregroundStyle(.secondary)
                    }
                }

                Section {
                    Text("네트워크 상태를 실시간으로 모니터링합니다.")
                        .font(.caption)
                        .foregroundStyle(.secondary)
                }
            }
            .navigationTitle("네트워크 모니터")
        }
    }

    private func connectionTypeString(_ type: NWInterface.InterfaceType) -> String {
        switch type {
        case .wifi: return "Wi-Fi"
        case .cellular: return "셀룰러"
        case .wiredEthernet: return "유선 이더넷"
        case .loopback: return "로컬"
        case .other: return "기타"
        @unknown default: return "알 수 없음"
        }
    }
}

💡 HIG Guidelines

Permission Settings: Add NSLocalNetworkUsageDescription to Info.plist
Bonjour 서비스: Specify service types in NSBonjourServices
TLS 사용: 민감한 데이터 전송 시 TLS 필수
네트워크 효율: Check isExpensive to optimize large downloads
Error Handling: 연결 실패, 타임아웃에 대한 적절한 처리

🎯 Practical Usage

실시간 통신: 채팅, 게임 서버 연동
IoT 통신: Smart home device control
로컬 서버: 디버깅용 로컬 서버 구현
서비스 검색: 로컬 네트워크의 프린터, 미디어 서버 찾기
P2P 통신: 직접적인 기기 간 통신

📚 Learn More

⚡️ Performance Tips: NWConnection automatically selects the optimal network path. It supports both IPv4 and IPv6, seamlessly switching between Wi-Fi and cellular. UDP is fast but unreliable, while TCP is reliable but has overhead.

📎 Apple Official Resources

📘 Documentation 🎬 WWDC Sessions