04 · 네트워크

import Foundation

// 커넥션 풀·TLS 세션 재개 정보·HTTP 캐시가 '세션 인스턴스'에 붙어 있다.
// (DNS 캐시는 세션이 아니라 OS 리졸버 mDNSResponder가 들고 있어 세션과 무관하게 공유된다.)
// 매번 새로 만들면 요청마다 TCP → TLS를 처음부터 다시 친다.

// ❌ 요청마다 새 세션 — 재사용 이점이 전부 사라진다
func fetchBad(_ url: URL) async throws -> Data {
    let session = URLSession(configuration: .default)
    return try await session.data(from: url).0
}

// ✅ 용도별로 하나씩 만들어 재사용한다
enum Net {
    /// 사용자가 화면에서 기다리는 API 호출
    static let api: URLSession = {
        let c = URLSessionConfiguration.default
        c.timeoutIntervalForRequest = 15
        c.timeoutIntervalForResource = 60
        c.httpMaximumConnectionsPerHost = 6
        c.waitsForConnectivity = true
        c.requestCachePolicy = .useProtocolCachePolicy
        return URLSession(configuration: c)
    }()

    /// 이미지·대용량 — 캐시 정책과 타임아웃이 다르다
    static let media: URLSession = {
        let c = URLSessionConfiguration.default
        c.timeoutIntervalForResource = 300
        c.urlCache = URLCache(memoryCapacity: 32 << 20, diskCapacity: 256 << 20)
        return URLSession(configuration: c)
    }()
}

// ⚠️ 세션은 delegate를 '강하게' 붙잡는다. delegate가 세션을 소유하면
//    session → self → session 순환이 되어 deinit이 아예 불리지 않는다.
//    따라서 무효화는 deinit이 아니라 '소유자가 끝내는 시점'에 명시적으로 호출해야 한다.
final class PinnedClient: NSObject, URLSessionDelegate {
    private lazy var session = URLSession(configuration: .default,
                                          delegate: self, delegateQueue: nil)
    /// 화면 종료·로그아웃 등 이 객체의 수명이 끝나는 지점에서 반드시 호출한다
    func shutdown() { session.finishTasksAndInvalidate() }
}

import Foundation

// "API가 느려요"는 진단이 아니다. DNS·TCP·TLS·TTFB·본문 중 어디인지에 따라
// 처방이 완전히 달라진다. URLSessionTaskMetrics가 이걸 다 알려준다.

final class MetricsCollector: NSObject, URLSessionTaskDelegate {

    func urlSession(_ session: URLSession, task: URLSessionTask,
                    didFinishCollecting metrics: URLSessionTaskMetrics) {
        for t in metrics.transactionMetrics {
            func ms(_ a: Date?, _ b: Date?) -> String {
                guard let a, let b else { return "-" }
                return String(format: "%.0fms", b.timeIntervalSince(a) * 1000)
            }

            print("""
            프로토콜: \(t.networkProtocolName ?? "-")  재사용: \(t.isReusedConnection)
              DNS   \(ms(t.domainLookupStartDate, t.domainLookupEndDate))
              연결   \(ms(t.connectStartDate, t.connectEndDate))   // TCP+TLS 합계(connectEnd는 TLS 완료 시점)
              └ TLS  \(ms(t.secureConnectionStartDate, t.secureConnectionEndDate))
              └ TCP  \(ms(t.connectStartDate, t.secureConnectionStartDate))
              TTFB  \(ms(t.requestEndDate, t.responseStartDate))
              본문   \(ms(t.responseStartDate, t.responseEndDate))
            """)
        }
    }
}

// 읽는 법 — 계층마다 처방이 다르다
//   DNS가 크다        → 콜드 조회. 세션 재사용·사전 워밍으로 완화
//   TLS가 크다        → 콜드 핸드셰이크. 커넥션 재사용, TLS 1.3 확인
//   TTFB가 크다       → 서버 처리 시간. 클라가 할 수 있는 게 없다 → 백엔드로
//   본문이 크다       → 페이로드 크기·압축 문제 → 응답을 줄이거나 페이지네이션
//   isReused=false만  → 풀이 안 돌고 있다 → 세션을 매번 만들고 있지 않은지 확인

let session = URLSession(configuration: .default,
                         delegate: MetricsCollector(), delegateQueue: nil)

import Foundation

// HTTP/1.1 시절 관행: 호스트당 커넥션 한도(기본 6개)를 우회하려고
// img1.cdn.com, img2.cdn.com … 으로 도메인을 쪼갰다(domain sharding).
//
// HTTP/2에서는 이게 역효과다. 한 커넥션에 스트림을 멀티플렉싱하는 게 핵심인데
// 도메인을 쪼개면 커넥션이 늘어 그 이점이 사라지고 핸드셰이크만 늘어난다.

// ❌ HTTP/2 서버에 대고 샤딩
let shardedHosts = ["img1.cdn.com", "img2.cdn.com", "img3.cdn.com"]

// ✅ 하나로 모아 멀티플렉싱을 받는다
let singleHost = "cdn.example.com"

// 실제로 h2로 붙었는지, 커넥션이 재사용되는지 확인한다
func verifyProtocol(_ metrics: URLSessionTaskMetrics) {
    let protocols = Set(metrics.transactionMetrics.compactMap(\.networkProtocolName))
    let reused = metrics.transactionMetrics.filter(\.isReusedConnection).count
    print("프로토콜 \(protocols) · 재사용 \(reused)/\(metrics.transactionMetrics.count)")
    // "h2"가 나오고 재사용 비율이 높아야 정상이다
}

// ✅ 서버가 HTTP/2를 지원하는지 먼저 확인
//    curl -I --http2 https://cdn.example.com/  →  "HTTP/2 200"

// ⚠️ 한도 설정도 프로토콜에 맞춰 생각한다
let config = URLSessionConfiguration.default
config.httpMaximumConnectionsPerHost = 6   // HTTP/1.1 폴백 시에만 의미가 있다
// HTTP/2에서는 이 값과 무관하게 보통 커넥션 1개로 처리된다

GET /users/42 HTTP/1.1
Host: api.example.com
Accept: application/json
Connection: keep-alive

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 36

{"id":42,"name":"Ada","active":true}

import Foundation

// HTTP/2는 한 TCP 커넥션 위에서 여러 요청을 스트림으로 동시에 실어 나른다.
// 커넥션을 늘리는 건 이 설계를 거스르는 것이다.

// ✅ 같은 호스트로 여러 요청을 동시에 보내도 커넥션은 1개면 충분하다
func loadFeedAssets(_ urls: [URL]) async throws -> [Data] {
    try await withThrowingTaskGroup(of: Data.self) { group in
        for url in urls {
            group.addTask { try await Net.api.data(from: url).0 }
        }
        var out: [Data] = []
        for try await d in group { out.append(d) }
        return out
    }
}
// HTTP/2라면 20개 요청 → 커넥션 1개 · 스트림 20개
// HTTP/1.1이라면      → 커넥션 6개(URLSession 기본값) · 나머지는 큐 대기

// ✅ 서버 푸시 대신 이제는 Early Hints·preload를 쓴다(서버 설정 영역)

// ⚠️ HTTP/2에서도 남는 것: TCP 계층 head-of-line 블로킹.
//    패킷 하나가 유실되면 그 커넥션의 모든 스트림이 함께 기다린다.
//    → 이걸 없앤 게 QUIC(HTTP/3)이다.

enum Net {
    static let api = URLSession(configuration: .default)
}

import Foundation

// 모바일은 Wi-Fi ↔ 셀룰러 전환이 잦다. TCP는 4-tuple(출발지 IP/포트)이 바뀌면
// 커넥션이 끊겨 핸드셰이크를 처음부터 다시 친다.
// QUIC은 connection ID로 식별해 IP가 바뀌어도 커넥션을 이어 간다(migration).

// ✅ URLSession은 서버가 지원하면 자동으로 HTTP/3를 쓴다 (Alt-Svc 협상)
//    별도 코드는 필요 없고, 실제로 붙었는지 확인만 하면 된다
func checkHTTP3(_ metrics: URLSessionTaskMetrics) {
    for t in metrics.transactionMetrics {
        if t.networkProtocolName == "h3" { print("HTTP/3로 연결됨") }
    }
}

// ✅ Network.framework을 직접 쓴다면 명시적으로 지정할 수 있다
import Network

func makeQUICConnection(host: String) -> NWConnection {
    let options = NWProtocolQUIC.Options(alpn: ["h3"])
    let params = NWParameters(quic: options)
    return NWConnection(host: NWEndpoint.Host(host), port: 443, using: params)
}

// ✅ 전환 상황을 실제로 테스트한다
//    · Network Link Conditioner로 대역폭·손실 조절
//    · 요청 중에 Wi-Fi를 끄고 셀룰러로 넘어가 보기
//    · TCP: 요청 실패 후 재시도 / QUIC: 그대로 이어짐

// ⚠️ 서버·CDN이 지원해야 의미가 있다. 확인:
//    curl -I --http3 https://api.example.com/
//    또는 응답 헤더의 alt-svc: h3=":443"

import Foundation

// 헤더·페이로드만 들여다보면 정작 원인이 TCP 재전송·혼잡 제어일 때 놓친다.

// ① 애플리케이션 계층 — URLSessionTaskMetrics로 단계별 시간
func appLayer(_ m: URLSessionTaskMetrics) {
    for t in m.transactionMetrics {
        let sent = t.countOfRequestBodyBytesSent
        let received = t.countOfResponseBodyBytesReceived
        print("요청 \(sent)B · 응답 \(received)B · \(t.networkProtocolName ?? "-")")
    }
}

// ② 전송 계층 — Network.framework의 path·경로 상태
import Network

let monitor = NWPathMonitor()

func watchPath() {
    monitor.pathUpdateHandler = { path in
        print("상태 \(path.status) · 비쌈 \(path.isExpensive) · 제한 \(path.isConstrained)")
        for i in path.availableInterfaces { print("  \(i.type) \(i.name)") }
    }
    monitor.start(queue: .global(qos: .utility))
}

/*  ③ 그 아래는 도구로 본다
      · Instruments → Network 템플릿 (재전송·RTT·윈도우)
      · Xcode → Debug Navigator → Network
      · 서버 쪽: ss -ti / netstat -s 로 retransmit 카운터

    판별 감각
      응답 크기는 작은데 시간이 길다     → TTFB(서버) 또는 RTT
      전송량 대비 시간이 비정상적으로 길다 → 재전송·혼잡 제어 의심
      특정 네트워크에서만 느리다         → 경로 문제(MTU·프록시·중간 장비)      */

// 신뢰성이 필요한 경우: TCP (여기서는 TLS over TCP)
let tcp = NWConnection(host: "example.com", port: 443, using: .tls)

// 지연에 민감하고 유실을 감내하는 경우: UDP
let udp = NWConnection(host: "example.com", port: 9000, using: .udp)

import Foundation
import Network

// 판단 기준은 "늦게 온 데이터가 쓸모 있는가"다.
//   쓸모 있다 → TCP (재전송으로 반드시 도착시킨다)
//   쓸모 없다 → UDP (지난 음성 프레임을 다시 받아도 의미가 없다)

// ✅ API·파일·이미지 — TCP(위에 TLS)
func makeAPIConnection() -> NWConnection {
    NWConnection(host: "api.example.com", port: 443, using: .tls)
}

// ✅ 실시간 음성·게임 상태 — UDP
func makeVoiceConnection() -> NWConnection {
    NWConnection(host: "voice.example.com", port: 9000, using: .udp)
}

// ⚠️ UDP를 고르면 아래를 전부 앱이 책임진다
struct VoicePacket: Codable {
    let sequence: UInt32      // ① 순서 — 뒤바뀜을 직접 정렬해야 한다
    let timestamp: UInt64     // ② 지연 판단 — 너무 늦은 건 버린다
    let payload: Data
}

final class JitterBuffer {
    private var packets: [UInt32: VoicePacket] = [:]
    private var nextSequence: UInt32 = 0

    // ③ 유실은 재전송하지 않고 '메운다'(concealment) — 실시간의 정석
    func pop() -> VoicePacket? {
        defer { nextSequence += 1 }
        if let p = packets.removeValue(forKey: nextSequence) { return p }
        return nil            // 유실 → 이전 프레임 반복이나 무음으로 대체
    }

    func push(_ p: VoicePacket) {
        guard p.sequence >= nextSequence else { return }   // ④ 너무 늦은 건 폐기
        packets[p.sequence] = p                            // ⑤ 중복도 자연히 제거
    }
}

import Foundation
import Network

// "UDP 위에 신뢰성을 얹는다"는 이미 수십 년간 다듬어진 문제다.
// 혼잡 제어 하나만 해도 직접 만들면 거의 반드시 틀린다.

// ✅ ① 신뢰성 있는 스트림이 필요하면 → QUIC (HTTP/3의 전송 계층)
func quicStream(host: String) -> NWConnection {
    let options = NWProtocolQUIC.Options(alpn: ["h3"])
    return NWConnection(host: NWEndpoint.Host(host), port: 443,
                        using: NWParameters(quic: options))
}
//    얻는 것: 재전송·순서·혼잡 제어·TLS 1.3·커넥션 마이그레이션·스트림별 독립 HOL

// ✅ ② 실시간 음성/영상이면 → WebRTC
//    얻는 것: 지터 버퍼, 에코 제거, 대역폭 추정, NAT 통과(ICE/STUN/TURN),
//            코덱 협상, FEC·PLC
//    이걸 직접 만드는 건 사실상 불가능하다.

// ✅ ③ 로컬 네트워크 피어 발견·연결이면 → Network.framework의 Bonjour
let listener = try? NWListener(using: .udp)
func advertise(_ l: NWListener) {
    l.service = NWListener.Service(name: "MyApp", type: "_myapp._udp")
}

// ✅ ④ 그래도 직접 만들어야 한다면, 최소한 이것들은 반드시 있어야 한다
//    · 시퀀스 번호 + ACK
//    · RTO(재전송 타임아웃) 추정 — 고정값 금지
//    · 혼잡 제어 (최소한 AIMD)
//    · 흐름 제어 (수신 버퍼 한계)
//    · MTU 고려 (조각화 회피, 보통 1200바이트 이하 페이로드)

// 판단: 위 목록을 보고 "이걸 우리가 유지보수할 수 있나?"를 먼저 물어본다.

import Foundation

// "첫 요청만 3초, 이후엔 200ms"는 거의 항상 DNS + TCP + TLS 콜드 비용이다.
// 서버가 느린 게 아니므로 백엔드를 붙잡고 있어도 답이 안 나온다.

final class ColdStartDiagnostics: NSObject, URLSessionTaskDelegate {
    func urlSession(_ s: URLSession, task: URLSessionTask,
                    didFinishCollecting m: URLSessionTaskMetrics) {
        guard let t = m.transactionMetrics.first else { return }

        func ms(_ a: Date?, _ b: Date?) -> Double {
            guard let a, let b else { return 0 }
            return b.timeIntervalSince(a) * 1000
        }

        let dns = ms(t.domainLookupStartDate, t.domainLookupEndDate)
        let tcp = ms(t.connectStartDate, t.connectEndDate)
        let tls = ms(t.secureConnectionStartDate, t.secureConnectionEndDate)
        let ttfb = ms(t.requestEndDate, t.responseStartDate)
        // connectEnd는 TLS 핸드셰이크 완료 시점이라 tcp 구간이 tls를 이미 포함한다 — 더하면 이중 계산이다
        let coldCost = dns + tcp          // = DNS + (TCP + TLS)

        print(String(format: "콜드 비용 %.0fms (DNS %.0f + TCP %.0f + TLS %.0f) · TTFB %.0fms",
                     coldCost, dns, tcp, tls, ttfb))

        if !t.isReusedConnection && coldCost > ttfb {
            print("→ 서버가 아니라 커넥션 수립이 병목이다")
        }
    }
}

// ✅ 완화 ① 세션을 살려 둔다 (커넥션 풀 재사용)
// ✅ 완화 ② TLS 1.3 확인 — 1-RTT, 재접속 시 0-RTT
// ✅ 완화 ③ 사전 워밍 (아래 항목)
// ✅ 완화 ④ 첫 화면에 필요한 요청 수 자체를 줄인다(배치 API)

import Foundation

// 사용자가 버튼을 누르기 전에 핸드셰이크를 미리 쳐 두면
// 실제 요청의 체감 지연이 콜드 비용만큼 사라진다.

enum Warmer {
    /// 앱 시작·로그인 화면 진입처럼 '곧 API를 쓸 것이 확실한' 시점에 호출한다
    static func warmUp() {
        var request = URLRequest(url: URL(string: "https://api.example.com/health")!)
        request.httpMethod = "HEAD"                 // 본문 없이 핸드셰이크만
        request.cachePolicy = .reloadIgnoringLocalCacheData

        Net.api.dataTask(with: request) { _, _, _ in
            // 결과는 쓰지 않는다. 목적은 커넥션을 풀에 올려 두는 것.
        }.resume()
    }
}

// AppDelegate / SceneDelegate에서
func applicationDidFinishLaunching() {
    Warmer.warmUp()
}

// ✅ 여러 호스트를 쓴다면 각각 데워야 한다 (풀은 호스트별이다)
enum MultiWarmer {
    static let hosts = ["api.example.com", "cdn.example.com"]
    static func warmAll() {
        for host in hosts {
            var r = URLRequest(url: URL(string: "https://\(host)/health")!)
            r.httpMethod = "HEAD"
            Net.api.dataTask(with: r).resume()
        }
    }
}

// ⚠️ 남용하지 말 것: 쓰지도 않을 커넥션을 데우면 배터리·데이터만 쓴다.
//    "곧 확실히 쓴다"가 성립할 때만.
// ⚠️ 커넥션은 유휴 상태로 오래 두면 서버·중간 장비가 끊는다.
//    워밍은 '직전'에 해야 의미가 있다.

enum Net { static let api = URLSession(configuration: .default) }

// 멱등한 PATCH: 절대값 설정 — 몇 번 보내도 최종 상태 동일
PATCH /account/42   {"balance": 1000}

// 비멱등한 PATCH: 상대적 증감 — 보낼 때마다 효과 누적
PATCH /account/42   {"balance_delta": 100}

import Foundation

// 멱등성은 나중에 붙이는 게 아니라 스키마를 정할 때 결정된다.

// ❌ 상대적 증감 — 재시도할 때마다 효과가 누적된다
struct AddPointsRequest: Encodable {
    let delta: Int              // 100을 두 번 보내면 200이 더해진다
}

// ✅ 절대값 설정 — 몇 번을 보내도 최종 상태가 같다
struct SetPointsRequest: Encodable {
    let points: Int             // 500으로 설정. 재시도해도 500.
}

// ✅ 상대 연산이 꼭 필요하면 '버전'이나 '기대값'을 함께 보낸다 (낙관적 잠금)
struct AddPointsSafely: Encodable {
    let delta: Int
    let expectedCurrentVersion: Int   // 서버가 버전 불일치면 409로 거부
}

// ✅ 컬렉션 갱신도 마찬가지 — PUT(전체 교체)이 PATCH(부분 변경)보다 멱등하기 쉽다
struct ReplaceTagsRequest: Encodable {
    let tags: [String]          // 최종 상태를 통째로 보낸다
}

// 메서드별 기대 (GET·HEAD·PUT·DELETE·POST는 RFC 9110, PATCH는 RFC 5789)
//   GET·HEAD  safe + idempotent
//   PUT       idempotent  (전체 교체)
//   DELETE    idempotent  (없앤 상태로 수렴)
//   POST      비멱등      (멱등 키로 보완)
//   PATCH     설계에 따라 다름  ← 여기가 실무에서 갈리는 지점

func encodeExample() throws -> Data {
    try JSONEncoder().encode(SetPointsRequest(points: 500))
}

import Foundation

// POST가 본질적으로 비멱등이어도, 서버가 키로 중복을 걸러 주면
// 클라이언트는 안전하게 재시도할 수 있다.

struct CreateOrder: Encodable {
    let sku: String
    let quantity: Int
}

func createOrder(_ body: CreateOrder,
                 idempotencyKey: String) async throws -> Order {
    var request = URLRequest(url: URL(string: "https://api.example.com/orders")!)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.setValue(idempotencyKey, forHTTPHeaderField: "Idempotency-Key")
    request.httpBody = try JSONEncoder().encode(body)

    let (data, response) = try await Net.api.data(for: request)
    guard let http = response as? HTTPURLResponse else { throw NetError.invalidResponse }

    switch http.statusCode {
    case 200, 201:
        // ✅ 서버는 같은 키의 재요청에 '처음의 응답'을 그대로 재현해야 한다.
        //    200이든 201이든 클라는 성공으로 다룬다.
        return try JSONDecoder().decode(Order.self, from: data)
    case 409:
        // ⚠️ 서버가 이렇게 설계돼 있으면 클라가 '실패'로 오인한다 —
        //    서버 팀과 "재요청엔 원래 응답을 재현"으로 합의하는 편이 낫다
        throw NetError.duplicate
    case 422:
        // ✅ 같은 키인데 본문이 다르다 = 재시도가 아니라 버그/공격
        throw NetError.keyReuseWithDifferentBody
    default:
        throw NetError.http(http.statusCode)
    }
}

struct Order: Decodable {}
enum NetError: Error {
    case invalidResponse, duplicate, keyReuseWithDifferentBody, http(Int)
}
enum Net { static let api = URLSession(configuration: .default) }

import Foundation

// DELETE를 두 번 보내면 첫 번째는 204, 두 번째는 404가 흔하다.
// 최종 상태는 같으므로 멱등하지만, 클라가 404를 '실패'로 다루면
// 재시도 로직에서 사용자에게 잘못된 오류가 뜬다.

// ✅ 규칙을 코드 한 곳에 못 박는다
func delete(_ url: URL) async throws {
    var request = URLRequest(url: url)
    request.httpMethod = "DELETE"

    let (_, response) = try await Net.api.data(for: request)
    guard let http = response as? HTTPURLResponse else { throw NetError.invalidResponse }

    switch http.statusCode {
    case 200, 202, 204:
        return                       // 삭제됨
    case 404, 410:
        // ✅ "이미 없음"도 목표 상태에 도달한 것이므로 성공으로 취급한다
        return
    case 409:
        throw NetError.conflict      // 삭제할 수 없는 상태 (예: 진행 중 주문)
    default:
        throw NetError.http(http.statusCode)
    }
}

// ⚠️ 단, 화면에 따라 구분이 필요할 수도 있다.
//    "삭제했습니다" vs "이미 삭제된 항목입니다"를 다르게 보여줘야 한다면
//    성공/부재를 값으로 구분해 돌려준다.
enum DeleteOutcome { case deleted, alreadyAbsent }

func deleteDetailed(_ url: URL) async throws -> DeleteOutcome {
    var request = URLRequest(url: url)
    request.httpMethod = "DELETE"
    let (_, response) = try await Net.api.data(for: request)
    let code = (response as? HTTPURLResponse)?.statusCode ?? 0
    switch code {
    case 200, 202, 204: return .deleted
    case 404, 410:      return .alreadyAbsent
    default:            throw NetError.http(code)
    }
}

enum NetError: Error { case invalidResponse, conflict, http(Int) }
enum Net { static let api = URLSession(configuration: .default) }

do {
    let (data, response) = try await session.data(for: request)
    guard let http = response as? HTTPURLResponse else {
        throw AppError.invalidResponse
    }
    switch http.statusCode {
    case 200..<300:
        return try decoder.decode(User.self, from: data)   // 성공
    case 401:
        throw AppError.unauthorized       // 토큰 갱신 필요
    case 400..<500:
        throw AppError.client(http.statusCode)   // 재시도 무의미
    case 500..<600:
        throw AppError.server(http.statusCode)   // 조건부 재시도
    default:
        throw AppError.unexpected(http.statusCode)
    }
} catch let urlError as URLError {
    // ↓ 여기는 '응답을 못 받은' transport 계층
    switch urlError.code {
    case .timedOut, .networkConnectionLost, .cannotConnectToHost:
        throw AppError.retriableTransport(urlError)
    case .notConnectedToInternet:
        throw AppError.offline
    case .secureConnectionFailed, .serverCertificateUntrusted:
        throw AppError.tls(urlError)
    default:
        throw AppError.transport(urlError)
    }
}

import Foundation

// 4xx·5xx는 '통신 성공 + 애플리케이션 실패'다. error는 nil이고
// 실패 정보는 statusCode에만 있다. 이걸 놓치는 게 가장 흔한 버그다.

// ❌ 콜백 API에서의 전형적인 실수
func fetchBad(_ url: URL, completion: @escaping (Data?) -> Void) {
    URLSession.shared.dataTask(with: url) { data, response, error in
        guard error == nil else { completion(nil); return }
        completion(data)          // 💥 500 응답의 에러 HTML을 성공으로 넘긴다
    }.resume()
}

// ✅ 두 자리를 모두 본다
func fetch(_ url: URL, completion: @escaping (Result<Data, NetError>) -> Void) {
    URLSession.shared.dataTask(with: url) { data, response, error in
        if let error { completion(.failure(.transport(error))); return }
        guard let http = response as? HTTPURLResponse, let data else {
            completion(.failure(.invalidResponse)); return
        }
        guard (200..<300).contains(http.statusCode) else {
            completion(.failure(.http(http.statusCode, data))); return
        }
        completion(.success(data))
    }.resume()
}

// ✅ async/await에서도 동일하다 — throw는 transport 오류만 발생시킨다
func load(_ url: URL) async throws -> Data {
    let (data, response) = try await URLSession.shared.data(from: url)
    //                     ↑ 여기서 throw되는 건 transport 계층 오류뿐이다
    guard let http = response as? HTTPURLResponse else { throw NetError.invalidResponse }
    guard (200..<300).contains(http.statusCode) else {
        throw NetError.http(http.statusCode, data)   // ✅ 상태 코드를 직접 검사
    }
    return data
}

enum NetError: Error {
    case transport(Error), invalidResponse, http(Int, Data)
}

import Foundation

enum Failure {
    case transport(URLError)      // 응답 자체를 못 받음
    case http(Int)                // 응답은 받았고 상태 코드가 오류
}

// ✅ 재시도 여부는 '계층 × 멱등성'으로 결정된다
func shouldRetry(_ failure: Failure, isIdempotent: Bool) -> Bool {
    switch failure {
    case .http(let code):
        switch code {
        case 408, 429:            return true               // 타임아웃·레이트리밋
        case 500, 502, 503, 504:  return true               // 일시적 서버 오류
        case 501:                 return false              // 미구현 — 재시도 무의미
        case 400..<500:           return false              // ✅ 4xx는 재시도 금지
        default:                  return false
        }
    case .transport(let e):
        // ⚠️ 여기가 위험 구간 — 서버에 도달했는지 알 수 없다
        let retriableCodes: Set<URLError.Code> = [
            .timedOut, .networkConnectionLost, .cannotConnectToHost,
            .dnsLookupFailed, .notConnectedToInternet
        ]
        guard retriableCodes.contains(e.code) else { return false }
        return isIdempotent       // ✅ 멱등할 때만 재시도
    }
}

// 사용
func attempt(_ endpoint: Endpoint, failure: Failure, count: Int) -> Bool {
    count < 3 && shouldRetry(failure, isIdempotent: endpoint.isIdempotent)
}

struct Endpoint {
    let path: String
    let isIdempotent: Bool
}

import Foundation

// 원인 계층이 다르면 사용자가 할 수 있는 행동도 다르다.
// "오류가 발생했습니다" 하나로 뭉치면 사용자가 아무것도 못 한다.

enum AppError: Error {
    case offline
    case timeout
    case server(Int)
    case client(Int)
    case unauthorized
    case rateLimited(retryAfter: TimeInterval?)
    case transport(URLError.Code)     // TLS 실패·인증서 미신뢰·호스트 못 찾음 등 (재시도해도 동일)
}

extension AppError {
    /// 무엇이 잘못됐는지 + 사용자가 무엇을 할 수 있는지
    var userMessage: (title: String, body: String, action: String?) {
        switch self {
        case .offline:
            return ("연결 없음", "네트워크 연결을 확인해 주세요.", "다시 시도")
        case .timeout:
            return ("응답 지연", "네트워크가 불안정합니다.", "다시 시도")
        case .server:
            return ("일시적 오류", "잠시 후 다시 시도해 주세요.", "다시 시도")
        case .unauthorized:
            return ("로그인 필요", "다시 로그인해 주세요.", "로그인")
        case .rateLimited(let after):
            let s = after.map { "\(Int($0))초 후" } ?? "잠시 후"
            return ("요청이 많습니다", "\(s) 다시 시도해 주세요.", nil)
        case .client:
            return ("요청 오류", "입력 내용을 확인해 주세요.", nil)
        case .transport:
            return ("연결할 수 없음", "보안 연결에 실패했습니다. 네트워크 환경을 확인해 주세요.", nil)
        }
    }

    /// 재시도 버튼을 보여줄지도 계층에서 결정된다
    var isRetriable: Bool {
        switch self {
        case .offline, .timeout, .server, .rateLimited: return true
        case .client, .unauthorized, .transport:        return false
        }
    }
}

// 매핑은 한곳에서
func map(status: Int?, error: URLError?) -> AppError {
    if let error {
        switch error.code {
        case .notConnectedToInternet: return .offline
        case .timedOut:               return .timeout
        default:                      return .transport(error.code)   // 서버 오류로 뭉뚱그리면 무한 재시도가 된다
        }
    }
    switch status ?? 0 {
    case 401:        return .unauthorized
    case 429:        return .rateLimited(retryAfter: nil)
    case 500..<600:  return .server(status ?? 500)
    default:         return .client(status ?? 400)
    }
}

func urlSession(_ session: URLSession,
                didReceive challenge: URLAuthenticationChallenge,
                completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void) {
    guard challenge.protectionSpace.authenticationMethod
            == NSURLAuthenticationMethodServerTrust,
          let trust = challenge.protectionSpace.serverTrust else {
        completionHandler(.performDefaultHandling, nil); return
    }
    // 1) 먼저 시스템 기본 검증(체인·호스트명·만료)을 '실제로 수행'한다.
    //    이 호출을 빼면 만료·호스트명 불일치 인증서도 통과시키는 delegate가 된다.
    var trustError: CFError?
    guard SecTrustEvaluateWithError(trust, &trustError) else {
        completionHandler(.cancelAuthenticationChallenge, nil); return
    }
    // 2) 그다음 서버 공개키 해시가 '핀 집합(현재 + 백업)'에 있는지 대조
    if isPinned(trust, against: pinnedKeyHashes) {
        completionHandler(.useCredential, URLCredential(trust: trust))
    } else {
        completionHandler(.cancelAuthenticationChallenge, nil)
    }
}

import Foundation
import CryptoKit

// 핀을 하나만 박으면 서버 인증서를 교체하는 순간 전 사용자가 접속 불가가 된다.
// 앱은 심사·배포에 며칠이 걸리므로 되돌릴 방법도 없다.

enum Pinning {
    /// 현재 인증서 + 다음 인증서(백업). 교체 전에 백업 핀을 먼저 배포해 둔다.
    static let publicKeyHashes: Set<String> = [
        "current-spki-sha256-base64=",
        "backup-spki-sha256-base64="      // ✅ 차기 인증서용
    ]

    /// SPKI(공개키) 해시를 계산한다 — 인증서 전체가 아니라 공개키를 핀한다.
    /// 인증서를 갱신해도 키를 유지하면 핀이 그대로 유효하다.
    static func spkiHash(of certificate: SecCertificate) -> String? {
        guard let key = SecCertificateCopyKey(certificate),
              let data = SecKeyCopyExternalRepresentation(key, nil) as Data?
        else { return nil }
        // 실제로는 ASN.1 SPKI 헤더를 앞에 붙여야 표준 핀과 일치한다
        return Data(SHA256.hash(data: data)).base64EncodedString()
    }

    static func isPinned(_ trust: SecTrust) -> Bool {
        guard let chain = SecTrustCopyCertificateChain(trust) as? [SecCertificate]
        else { return false }
        for cert in chain {
            if let hash = spkiHash(of: cert), publicKeyHashes.contains(hash) {
                return true
            }
        }
        return false
    }
}

// ⚠️ 핀 로테이션 절차를 문서로 못 박아 둔다
//   1) 차기 키를 만들고 그 핀을 앱에 '추가'해 배포 (현재 + 백업 둘 다 유효)
//   2) 사용자 대부분이 그 버전으로 올라올 때까지 대기 (수 주)
//   3) 서버 인증서를 차기 키로 교체
//   4) 다음 릴리스에서 옛 핀 제거 + 새 백업 핀 추가

import Foundation

// 핀이 만료되는데 사용자가 앱을 업데이트하지 않으면 그 사용자는 영구 차단이다.
// 그래서 피닝을 켜는 순간 "앱을 강제로 올릴 수단"이 필수가 된다.

// ✅ ① 핀에 만료일을 넣고, 다가오면 사용자에게 알린다
struct Pin {
    let hash: String
    let expiresAt: Date
}

enum PinStore {
    static let pins: [Pin] = [
        Pin(hash: "current...", expiresAt: Date(timeIntervalSince1970: 1_800_000_000)),
        Pin(hash: "backup...",  expiresAt: Date(timeIntervalSince1970: 1_900_000_000))
    ]

    /// 모든 핀이 만료되기 전에 업데이트를 유도해야 한다
    static var latestExpiry: Date { pins.map(\.expiresAt).max() ?? .distantPast }

    static var daysUntilLockout: Int {
        Calendar.current.dateComponents([.day], from: Date(), to: latestExpiry).day ?? 0
    }
}

// ✅ ② 원격 설정으로 최소 지원 버전을 내려 강제 업데이트를 건다
struct RemoteConfig: Decodable {
    let minimumSupportedVersion: String
    let forceUpdateMessage: String
}

@MainActor
func checkForcedUpdate(_ config: RemoteConfig) -> Bool {
    let current = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "0"
    return current.compare(config.minimumSupportedVersion,
                           options: .numeric) == .orderedAscending
}

// ✅ ③ 만료가 임박하면 미리 경고 (차단되기 전에)
func warnIfPinExpiringSoon() {
    if PinStore.daysUntilLockout < 30 {
        print("⚠️ 핀 만료 \(PinStore.daysUntilLockout)일 전 — 업데이트 유도 필요")
    }
}

// ⚠️ 강제 업데이트 화면 자체는 피닝된 API를 거치지 않아야 한다.
//    핀이 깨진 상태에서 "업데이트하세요"조차 못 받으면 아무것도 못 한다.

import Foundation

// 프록시(Charles·Proxyman)로 디버깅하려면 피닝을 꺼야 한다.
// 그 스위치가 릴리스에 새면 피닝을 켠 의미가 사라진다.

// ✅ 컴파일 단계에서 배제한다 — 런타임 플래그면 코드가 바이너리에 남는다
#if DEBUG && ALLOW_PROXY_DEBUG
let isPinningEnabled = false
#else
let isPinningEnabled = true
#endif

final class PinnedSessionDelegate: NSObject, URLSessionDelegate {
    func urlSession(_ session: URLSession,
                    didReceive challenge: URLAuthenticationChallenge,
                    completionHandler: @escaping (URLSession.AuthChallengeDisposition,
                                                  URLCredential?) -> Void) {
        guard isPinningEnabled else {
            completionHandler(.performDefaultHandling, nil)   // 디버그 빌드만 도달
            return
        }
        guard challenge.protectionSpace.authenticationMethod
                == NSURLAuthenticationMethodServerTrust,
              let trust = challenge.protectionSpace.serverTrust else {
            completionHandler(.performDefaultHandling, nil)
            return
        }
        // ① 시스템 기본 검증(체인·호스트명·만료)을 먼저 통과시키고
        // ② 그다음 핀을 대조한다 — 순서를 바꾸면 안 된다
        if Pinning.isPinned(trust) {
            completionHandler(.useCredential, URLCredential(trust: trust))
        } else {
            completionHandler(.cancelAuthenticationChallenge, nil)
        }
    }
}

/*  ALLOW_PROXY_DEBUG는 Debug 구성에만 정의한다
      Build Settings → Swift Compiler - Custom Flags
        → Active Compilation Conditions
          Debug:   DEBUG ALLOW_PROXY_DEBUG
          Release: (비움)

    ✅ 릴리스 바이너리에 문자열이 남지 않았는지 확인
       strings MyApp.app/MyApp | grep -i proxy                                 */

enum Pinning { static func isPinned(_ t: SecTrust) -> Bool { true } }

let config = URLSessionConfiguration.default
config.timeoutIntervalForRequest  = 30    // 데이터가 30초간 안 오면(정체) 실패
config.timeoutIntervalForResource = 120   // 전체가 120초를 넘으면 실패
config.waitsForConnectivity       = true  // 오프라인이면 즉시 실패 대신 대기
let session = URLSession(configuration: config)

var req = URLRequest(url: url)
req.timeoutInterval = 15   // 이 요청만 request timeout을 15초로 덮어씀

import Foundation

// 두 값의 의미가 완전히 다르다. 하나만 잡으면 반쪽짜리 방어다.
//   timeoutIntervalForRequest  = "데이터가 멈춰 있는 시간"의 상한 (흐르면 리셋)
//   timeoutIntervalForResource = 요청 전체의 총 예산 (재시도 포함)

let config = URLSessionConfiguration.default
config.timeoutIntervalForRequest  = 15      // 기본 60
config.timeoutIntervalForResource = 60      // 기본 604800(7일) ← 이걸 안 잡으면 사실상 무제한

// ❌ request만 15로 잡았을 때 생기는 일:
//    서버가 1초에 1바이트씩 흘려보내면 타이머가 계속 리셋되어 영원히 안 끊긴다.

// ✅ 요청 단위로 덮어쓸 수도 있다 (resource는 세션 설정만 가능)
func makeRequest(_ url: URL) -> URLRequest {
    var r = URLRequest(url: url)
    r.timeoutInterval = 10                  // 이 요청만 request timeout 10초
    return r
}

// ✅ async/await에서 '전체 시간'을 더 강하게 제어하고 싶다면 Task 레벨에서
func fetchWithDeadline(_ url: URL, within duration: Duration) async throws -> Data {
    try await withThrowingTaskGroup(of: Data.self) { group in
        group.addTask { try await URLSession.shared.data(from: url).0 }
        group.addTask {
            try await Task.sleep(for: duration)
            throw NetError.deadlineExceeded
        }
        let first = try await group.next()!
        group.cancelAll()                   // 나머지 취소
        return first
    }
}

enum NetError: Error { case deadlineExceeded }

import Foundation

// 인터랙티브 API와 백그라운드 대용량 다운로드는 요구가 정반대다.
// 하나의 세션으로 둘 다 하려 하면 어느 쪽도 맞지 않는다.

enum Sessions {

    /// 사용자가 화면에서 기다린다 — 짧게 끊고 빨리 실패시킨다
    static let interactive: URLSession = {
        let c = URLSessionConfiguration.default
        c.timeoutIntervalForRequest = 15
        c.timeoutIntervalForResource = 45
        c.waitsForConnectivity = false        // 오프라인이면 즉시 실패시켜 UI를 돌려준다
        c.requestCachePolicy = .useProtocolCachePolicy
        return URLSession(configuration: c)
    }()

    /// 사용자가 기다리지 않는다 — 오래 걸려도 되고, 연결을 기다려도 된다
    static let deferred: URLSession = {
        let c = URLSessionConfiguration.default
        c.timeoutIntervalForRequest = 60
        c.timeoutIntervalForResource = 60 * 30
        c.waitsForConnectivity = true         // 연결될 때까지 대기
        c.allowsExpensiveNetworkAccess = false // 셀룰러·핫스팟 회피
        return URLSession(configuration: c)
    }()

    /// 앱이 종료돼도 계속되는 대용량 다운로드
    static let background: URLSession = {
        let c = URLSessionConfiguration.background(withIdentifier: "com.app.bulk")
        c.timeoutIntervalForRequest = 90
        c.timeoutIntervalForResource = 60 * 60 * 24
        c.isDiscretionary = true              // 시스템이 좋은 시점을 고른다
        c.sessionSendsLaunchEvents = true
        return URLSession(configuration: c, delegate: BulkDelegate(), delegateQueue: nil)
    }()
}

final class BulkDelegate: NSObject, URLSessionDownloadDelegate {
    func urlSession(_ s: URLSession, downloadTask: URLSessionDownloadTask,
                    didFinishDownloadingTo location: URL) {}
}

import Foundation

// timeout을 감으로 정하면 두 방향으로 다 틀린다.
//   너무 짧다 → 정상 요청이 끊긴다. 게다가 서버는 이미 처리했을 수 있어
//                비멱등 요청의 재시도 중복 위험이 커진다.
//   너무 길다 → 사용자가 하염없이 기다린다.

// ✅ 기준: 서버의 p99 지연 + 네트워크 여유
//    예) 결제 API의 p99가 3.2초라면 → 3.2 + 여유 ≈ 8~10초
struct TimeoutPolicy {
    let serverP99: TimeInterval
    let networkMargin: TimeInterval

    var requestTimeout: TimeInterval { serverP99 * 2 + networkMargin }
}

let payment = TimeoutPolicy(serverP99: 3.2, networkMargin: 3)   // → 9.4초

// ✅ 클라이언트에서 실제 분포를 수집해 검증한다
final class LatencyRecorder: NSObject, URLSessionTaskDelegate {
    private var samples: [TimeInterval] = []

    func urlSession(_ s: URLSession, task: URLSessionTask,
                    didFinishCollecting m: URLSessionTaskMetrics) {
        samples.append(m.taskInterval.duration)
    }

    func percentile(_ p: Double) -> TimeInterval {
        guard !samples.isEmpty else { return 0 }
        let sorted = samples.sorted()
        let index = Int(Double(sorted.count - 1) * p)
        return sorted[index]
    }

    func report() {
        print(String(format: "p50 %.2fs · p95 %.2fs · p99 %.2fs",
                     percentile(0.5), percentile(0.95), percentile(0.99)))
    }
}

// ⚠️ 클라 timeout < 서버 처리 시간이면 "서버는 성공, 클라는 timeout"이 상시로 생긴다.
//    이 조합에서 비멱등 요청을 재시도하면 이중 실행이 된다 → Q9의 멱등 키가 필수.

func post(_ body: Data, to url: URL,
          idempotencyKey: String,           // 재시도 전체에서 '동일'해야 함
          maxAttempts: Int = 3) async throws -> Data {
    var attempt = 0
    while true {
        attempt += 1
        do {
            var req = URLRequest(url: url)
            req.httpMethod = "POST"
            req.httpBody = body
            req.setValue(idempotencyKey, forHTTPHeaderField: "Idempotency-Key")
            let (data, resp) = try await session.data(for: req)
            let code = (resp as? HTTPURLResponse)?.statusCode ?? 0
            if (200..<300).contains(code) { return data }
            // 5xx·429만 재시도 대상, 그 외(4xx 등)는 즉시 던짐
            guard code == 429 || (500..<600).contains(code), attempt < maxAttempts
            else { throw AppError.http(code) }
        } catch let e as URLError where
                    e.code == .timedOut || e.code == .networkConnectionLost {
            // transport 오류: 멱등키가 있으니 재시도 안전
            if attempt >= maxAttempts { throw e }
        }
        // 지수 백오프 + 지터
        let backoff = pow(2.0, Double(attempt)) * 0.2
        let jitter  = Double.random(in: 0...0.3)
        try await Task.sleep(for: .seconds(backoff + jitter))
    }
}

import Foundation

// 재시도들이 '같은 논리적 연산'임을 서버가 알아보려면 키가 동일해야 한다.
// 키를 루프 안에서 만들면 매 시도가 새 연산이 되어 멱등성이 무의미해진다.

struct IdempotentRequest {
    let url: URL
    let body: Data
    /// ✅ 요청을 '시작'할 때 한 번만 만든다. 모든 재시도가 이 값을 공유한다.
    let key: String = UUID().uuidString
}

func send(_ req: IdempotentRequest, maxAttempts: Int = 4) async throws -> Data {
    var lastError: Error?

    for attempt in 1...maxAttempts {
        var request = URLRequest(url: req.url)
        request.httpMethod = "POST"
        request.httpBody = req.body
        request.setValue(req.key, forHTTPHeaderField: "Idempotency-Key")  // ✅ 항상 같은 키

        do {
            let (data, response) = try await Net.api.data(for: request)
            let code = (response as? HTTPURLResponse)?.statusCode ?? 0
            if (200..<300).contains(code) { return data }
            guard code == 429 || (500..<600).contains(code) else {
                throw NetError.http(code)          // 4xx는 재시도하지 않는다
            }
            lastError = NetError.http(code)
        } catch let e as URLError where e.isRetriable {
            lastError = e
        }

        guard attempt < maxAttempts else { break }
        try await Task.sleep(for: backoff(attempt: attempt))
    }
    throw lastError ?? NetError.exhausted
}

// ✅ 오프라인 큐에 넣을 때도 키를 함께 저장한다 — 앱 재시작 후 재전송도 같은 신원
struct QueuedRequest: Codable {
    let key: String
    let url: URL
    let body: Data
    let createdAt: Date
}

extension URLError {
    var isRetriable: Bool {
        [.timedOut, .networkConnectionLost, .cannotConnectToHost].contains(code)
    }
}
enum NetError: Error { case http(Int), exhausted }
enum Net { static let api = URLSession(configuration: .default) }
func backoff(attempt: Int) -> Duration { .seconds(1) }

import Foundation

// 지터가 없으면 장애가 복구되는 순간 모든 클라이언트가 동시에 재시도해
// 서버를 다시 무너뜨린다(thundering herd).

struct RetryPolicy {
    var maxAttempts = 4
    var baseDelay: TimeInterval = 1
    var maxDelay: TimeInterval = 30
    var maxTotalDuration: TimeInterval = 60

    /// full jitter — 0 ~ 지수 상한 사이에서 균등 추출 (AWS 권장 방식)
    func delay(attempt: Int) -> Duration {
        let exponential = min(baseDelay * pow(2, Double(attempt - 1)), maxDelay)
        return .seconds(Double.random(in: 0...exponential))
    }
}

func withRetry<T>(_ policy: RetryPolicy = .init(),
                  operation: (Int) async throws -> T) async throws -> T {
    let deadline = Date().addingTimeInterval(policy.maxTotalDuration)
    var lastError: Error?

    for attempt in 1...policy.maxAttempts {
        do { return try await operation(attempt) }
        catch { lastError = error }

        guard attempt < policy.maxAttempts, Date() < deadline else { break }
        try await Task.sleep(for: policy.delay(attempt: attempt))
    }
    throw lastError!
}

// 지터 유무의 차이를 눈으로 보면 이해가 쉽다
func illustrate() {
    let p = RetryPolicy()
    print("지터 없음: 1s, 2s, 4s, 8s   ← 모든 클라이언트가 같은 시각에 몰린다")
    print("지터 있음: \((1...4).map { p.delay(attempt: $0) })  ← 흩어진다")
}

// ⚠️ 상한은 '횟수'와 '총 시간' 둘 다 둔다. 횟수만 두면 백오프가 길어질 때
//    사용자가 몇 분을 기다리게 된다.

import Foundation

// 429·503에 서버가 Retry-After를 주면, 그건 "언제 다시 오라"는 명시적 지시다.
// 자체 백오프보다 우선한다 — 서버가 자기 상태를 가장 잘 안다.

func retryDelay(from response: HTTPURLResponse,
                fallback: Duration) -> Duration {
    guard let value = response.value(forHTTPHeaderField: "Retry-After") else {
        return fallback
    }

    // 형식 ①: 초 단위 정수  →  Retry-After: 120
    if let seconds = Double(value) {
        return .seconds(seconds)
    }

    // 형식 ②: HTTP-date  →  Retry-After: Wed, 21 Oct 2026 07:28:00 GMT
    let formatter = DateFormatter()
    formatter.locale = Locale(identifier: "en_US_POSIX")
    formatter.timeZone = TimeZone(identifier: "GMT")
    formatter.dateFormat = "EEE, dd MMM yyyy HH:mm:ss zzz"
    if let date = formatter.date(from: value) {
        let interval = max(0, date.timeIntervalSinceNow)
        return .seconds(interval)
    }

    return fallback
}

// 사용
func handle(_ response: HTTPURLResponse, attempt: Int) async throws {
    guard response.statusCode == 429 || response.statusCode == 503 else { return }
    let wait = retryDelay(from: response, fallback: .seconds(pow(2, Double(attempt))))

    // ⚠️ 서버가 아주 긴 값을 줄 수도 있다 — 상한을 걸어 UI가 멈추지 않게 한다
    let capped = min(wait, .seconds(60))
    try await Task.sleep(for: capped)
}

// ⚠️ Retry-After가 매우 길면 재시도 대신 사용자에게 알리는 편이 낫다
func decide(_ wait: Duration) -> String {
    wait > .seconds(30) ? "사용자에게 안내 후 종료" : "자동 재시도"
}

import Foundation

// ❌ ① 4xx 재시도 — 요청 자체가 잘못됐으므로 몇 번을 보내도 같은 결과다.
//        서버 부하만 늘고 사용자는 더 오래 기다린다.
func badRetryOn4xx(_ code: Int) -> Bool {
    (400..<600).contains(code)          // 💥 400·401·404까지 재시도한다
}
func goodRetryOn4xx(_ code: Int) -> Bool {
    code == 408 || code == 429 || (500..<600).contains(code)   // ✅
}

// ❌ ② 지터 없는 즉시 재시도 — 장애 복구 순간 모든 기기가 동시에 몰린다
func badBackoff(attempt: Int) -> Duration {
    .seconds(pow(2, Double(attempt)))   // 전 사용자가 정확히 같은 시각에 재시도
}
func goodBackoff(attempt: Int) -> Duration {
    let cap = min(pow(2, Double(attempt)), 30)
    return .seconds(Double.random(in: 0...cap))   // ✅ full jitter
}

// ❌ ③ 멱등 키 없는 결제 POST를 타임아웃만 보고 재시도 — 이중 결제 직행
func badPaymentRetry(_ body: Data) async throws {
    for _ in 0..<3 {
        do { _ = try await post("/payments", body: body); return }
        catch { continue }              // 💥 서버가 이미 처리했을 수 있다
    }
}

// ✅ 키가 없으면 재시도하지 말고, 대신 '조회'로 결과를 확인한다
func safePaymentFlow(_ body: Data, key: String?) async throws {
    guard let key else {
        // 멱등 키를 서버가 지원하지 않으면 재시도 자체가 위험하다
        // → 사용자에게 "처리 여부를 확인 중"으로 안내하고 조회 API로 확인
        _ = try await get("/payments/status")
        return
    }
    _ = try await post("/payments", body: body, idempotencyKey: key)   // ✅ 안전
}

func post(_ path: String, body: Data,
          idempotencyKey: String? = nil) async throws -> Data { Data() }
func get(_ path: String) async throws -> Data { Data() }