16 · 분산 시스템과 모바일 클라이언트

func shouldRetry(_ error: URLError, method: HTTPMethod) -> Bool {
    switch error.code {
    // 요청이 서버에 닿기 전 실패 → 부수효과 없음, 항상 안전
    case .cannotFindHost, .cannotConnectToHost, .notConnectedToInternet:
        return true
    // 이미 전송한 뒤 응답을 못 받음 → 서버가 처리했을 수 있다
    case .timedOut, .networkConnectionLost:
        return method.isIdempotent   // 멱등일 때만 재시도
    default:
        return false
    }
}

func send(_ req: URLRequest, method: HTTPMethod, maxAttempts: Int = 3) async throws -> Data {
    var attempt = 0
    while true {
        do {
            let (data, resp) = try await URLSession.shared.data(for: req)
            guard let http = resp as? HTTPURLResponse else { return data }
            if (200...299).contains(http.statusCode) { return data }
            // 429(rate limit)는 서버가 처리 안 함 → 항상 재시도 안전.
            // 5xx는 처리 여부 불확실 → 멱등일 때만 재시도(비멱등이면 이중 실행 위험).
            // 4xx(429 제외)는 재시도해도 결과가 같음 → 재시도 무의미.
            let retryStatus = http.statusCode == 429
                || ((500...599).contains(http.statusCode) && method.isIdempotent)
            guard retryStatus, attempt + 1 < maxAttempts else {
                throw URLError(.badServerResponse)   // 재시도 불가·소진 → 상위로
            }
        } catch let e as URLError where shouldRetry(e, method: method) && attempt + 1 < maxAttempts {
            // 전송 계층 오류 재시도 → 아래 공통 백오프로 진입
        }
        // 여기 도달 = 재시도 확정 (성공·포기는 위에서 return/throw로 빠져나감)
        attempt += 1
        try Task.checkCancellation()
        let backoff = pow(2.0, Double(attempt)) * 0.2
        let jitter  = Double.random(in: 0...0.1)      // ⚠️ 소폭 가산 지터로는 부족하다 — 모든 클라이언트가 100ms 폭에 몰린다.
        //    full jitter(0 ~ 지수 상한 균등 추출)로 흩뿌려야 thundering herd를 막는다
        try await Task.sleep(nanoseconds: UInt64((backoff + jitter) * 1_000_000_000))
    }
}

import Foundation

// "GET은 안전, POST는 위험"은 부정확하다. 판단 기준은 메서드가 아니라
// '이 엔드포인트가 멱등한가'다. POST여도 서버가 멱등 키를 지원하면 안전하다.

struct Endpoint {
    let path: String
    let method: String

    /// 재시도해도 서버 상태의 최종 효과가 같은가
    let isIdempotent: Bool

    /// 재시도 시 멱등 키를 붙여야 하는가
    let requiresIdempotencyKey: Bool

    static let fetchFeed = Endpoint(
        path: "/feed", method: "GET",
        isIdempotent: true, requiresIdempotencyKey: false)

    static let createOrder = Endpoint(
        path: "/orders", method: "POST",
        isIdempotent: true,                    // ✅ 서버가 멱등 키를 지원한다
        requiresIdempotencyKey: true)

    static let sendAnalytics = Endpoint(
        path: "/events", method: "POST",
        isIdempotent: false,                   // 중복돼도 큰 문제는 없지만
        requiresIdempotencyKey: false)         // 재시도 대상은 아니다

    static let chargePayment = Endpoint(
        path: "/payments", method: "POST",
        isIdempotent: true,
        requiresIdempotencyKey: true)          // ⚠️ 키 없이는 절대 재시도 금지
}

// ✅ 재시도 판단을 한 곳에 모은다
func shouldRetry(_ endpoint: Endpoint, status: Int?, error: Error?) -> Bool {
    // 408·429·연결 실패처럼 '서버가 처리하지 않은 것이 확실한' 경우는 멱등성과 무관하게 안전하다
    if status == 408 || status == 429 { return true }
    if error?.code == .cannotConnectToHost { return true }
    guard endpoint.isIdempotent else { return false }

    if let status {
        return status == 408 || status == 429 || (500..<600).contains(status)
    }
    if let urlError = error as? URLError {
        return [.timedOut, .networkConnectionLost, .cannotConnectToHost]
            .contains(urlError.code)
    }
    return false
}

// ✅ 키 누락을 컴파일 타임에 가깝게 잡는다
func send(_ endpoint: Endpoint, key: String?) throws {
    if endpoint.requiresIdempotencyKey {
        guard key != nil else { throw ClientError.missingIdempotencyKey }
    }
}

enum ClientError: Error { case missingIdempotencyKey }

import Foundation

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

struct BackoffPolicy {
    var base: TimeInterval = 1
    var cap: TimeInterval = 30

    /// ❌ 지터 없음 — 전 사용자가 정확히 같은 시각에 몰린다
    func withoutJitter(attempt: Int) -> Duration {
        .seconds(min(base * pow(2, Double(attempt - 1)), cap))
        // 1s, 2s, 4s, 8s … 모든 기기가 동일
    }

    /// ✅ full jitter — 0 ~ 지수 상한 사이 균등 추출 (AWS 권장)
    func fullJitter(attempt: Int) -> Duration {
        let ceiling = min(base * pow(2, Double(attempt - 1)), cap)
        return .seconds(Double.random(in: 0...ceiling))
    }

    /// ✅ decorrelated jitter — 이전 대기에 기반해 더 고르게 퍼진다
    func decorrelated(previous: TimeInterval) -> Duration {
        let next = Double.random(in: base...(previous * 3))
        return .seconds(min(next, cap))
    }
}

// 분포를 눈으로 확인해 보면 차이가 명확하다
func illustrate() {
    let policy = BackoffPolicy()
    let without = (1...4).map { policy.withoutJitter(attempt: $0) }
    let with = (1...4).map { policy.fullJitter(attempt: $0) }
    print("지터 없음: \(without)")     // 항상 동일 → 동시에 몰린다
    print("지터 있음: \(with)")        // 매번 다름 → 흩어진다
}

// ⚠️ 지터는 '평균 대기'를 늘리지 않는다. 분산시킬 뿐이다.
//    full jitter의 기댓값은 지수 상한의 절반이라 오히려 평균은 짧아진다.

import Foundation

// 무한 재시도는 사용자 배터리·데이터를 태우고 서버 부하를 키운다.
// 횟수만 제한하면 백오프가 길어질 때 몇 분을 기다리게 된다.

struct RetryPolicy {
    var maxAttempts = 4
    var maxTotalDuration: Duration = .seconds(60)
    var base: TimeInterval = 1
    var cap: TimeInterval = 30

    func delay(attempt: Int) -> Duration {
        let ceiling = min(base * pow(2, Double(attempt - 1)), cap)
        return .seconds(Double.random(in: 0...ceiling))
    }
}

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

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

        guard attempt < policy.maxAttempts else { break }

        let wait = policy.delay(attempt: attempt)

        // ✅ 총 시간 상한을 넘으면 더 기다리지 않는다
        guard ContinuousClock.now + wait < deadline else { break }

        try await Task.sleep(for: wait)

        // ✅ 취소도 존중한다
        try Task.checkCancellation()
    }
    throw lastError ?? ClientError.exhausted
}

// ✅ 사용자 대면 요청과 백그라운드 작업의 정책을 분리한다
extension RetryPolicy {
    /// 화면에서 기다린다 — 빨리 포기하고 사용자에게 알린다
    static let interactive = RetryPolicy(
        maxAttempts: 2, maxTotalDuration: .seconds(10))

    /// 오프라인 큐 — 오래 버텨도 된다
    static let background = RetryPolicy(
        maxAttempts: 8, maxTotalDuration: .seconds(600), cap: 120)
}

enum ClientError: Error { case exhausted }

import Foundation

// 타임아웃은 '실패'가 아니라 '결과를 모름'이다.
// 서버가 이미 결제를 완료했을 수 있는데 재시도하면 이중 결제다.

// ❌ 이중 결제 직행 코드
func chargeBad(_ amount: Decimal) async throws {
    for _ in 0..<3 {
        do {
            _ = try await post("/payments", body: encode(amount))
            return
        } catch {
            continue                    // 💥 서버는 이미 처리했을 수 있다
        }
    }
}

// ✅ ① 서버가 멱등 키를 지원하면 — 키를 붙이고 재시도한다
func charge(_ amount: Decimal) async throws -> Receipt {
    let key = UUID().uuidString         // 루프 밖에서 한 번만

    return try await withRetry { _ in
        var request = URLRequest(url: paymentsURL)
        request.httpMethod = "POST"
        request.httpBody = encode(amount)
        request.setValue(key, forHTTPHeaderField: "Idempotency-Key")
        let (data, _) = try await URLSession.shared.data(for: request)
        return try JSONDecoder().decode(Receipt.self, from: data)
    }
}

// ✅ ② 지원하지 않으면 — 재시도하지 말고 '조회'로 확인한다
func chargeWithoutKey(_ amount: Decimal, requestID: String) async throws -> Receipt {
    do {
        return try await postPayment(amount, requestID: requestID)
    } catch is TimeoutError {
        // ⚠️ 재시도 금지. 대신 상태를 물어본다.
        return try await pollPaymentStatus(requestID: requestID)
    }
}

func pollPaymentStatus(requestID: String) async throws -> Receipt {
    for _ in 0..<10 {
        if let receipt = try await queryPayment(requestID) { return receipt }
        try await Task.sleep(for: .seconds(2))
    }
    throw ClientError.unknownOutcome     // 사용자에게 "확인 중"으로 안내
}

// ✅ ③ 그것도 안 되면 사용자에게 명확히 알린다
//    "결제 결과를 확인하는 중입니다. 다시 시도하지 마세요."
//    → 임의 재시도보다 훨씬 나은 UX다

struct Receipt: Decodable {}
struct TimeoutError: Error {}
enum ClientError: Error { case unknownOutcome }
let paymentsURL = URL(string: "https://api.example.com/payments")!
func encode(_ d: Decimal) -> Data { Data() }
func post(_ p: String, body: Data) async throws -> Data { Data() }
func postPayment(_ a: Decimal, requestID: String) async throws -> Receipt { Receipt() }
func queryPayment(_ id: String) async throws -> Receipt? { nil }
func withRetry<T>(_ op: (Int) async throws -> T) async throws -> T { try await op(1) }

struct PaymentRequest {
    let amount: Decimal
    let idempotencyKey: String   // 생성 시 한 번만 부여, 이후 불변

    init(amount: Decimal) {
        self.amount = amount
        self.idempotencyKey = UUID().uuidString
    }
}

func submit(_ payment: PaymentRequest) async throws -> Receipt {
    var req = URLRequest(url: paymentsURL)
    req.httpMethod = "POST"
    // 재시도해도 이 헤더 값은 동일 → 서버가 중복으로 인식
    req.setValue(payment.idempotencyKey, forHTTPHeaderField: "Idempotency-Key")
    req.httpBody = try JSONEncoder().encode(payment)
    let data = try await sendWithRetry(req)   // 내부에서 몇 번을 재시도해도 key 불변
    return try JSONDecoder().decode(Receipt.self, from: data)
}

-- 서버 측 설계. 키 기록과 실제 효과가 분리되면 그 틈에서 사고가 난다.

-- ❌ 캐시(Redis)에 키만 먼저 기록하고 DB는 따로
--    → "키는 있는데 결제는 롤백됨" 상태가 생긴다.
--      재시도가 오면 "이미 처리됨"으로 판단해 결제가 영영 안 된다.

-- ✅ 같은 트랜잭션 안에서 키 삽입과 부수효과를 함께 커밋한다
BEGIN;

  -- ① 키를 먼저 삽입한다. 유니크 위반이면 중복 요청이다.
  INSERT INTO idempotency_key (key, request_fingerprint, created_at, status)
       VALUES ($1, $2, now(), 'in_progress');
  --  UNIQUE(key) 제약이 동시 요청도 막아 준다

  -- ② 실제 부수효과
  INSERT INTO payment (order_id, amount, currency)
       VALUES ($3, $4, $5)
    RETURNING id INTO v_payment_id;

  UPDATE account SET balance = balance - $4 WHERE id = $6;

  -- ③ 응답을 저장해 재요청 시 그대로 재현할 수 있게 한다
  UPDATE idempotency_key
     SET status = 'completed', status_code = 201, response_body = $7
   WHERE key = $1;

COMMIT;
-- 어디서 실패하든 전부 롤백된다 — 키도, 결제도 남지 않는다

-- ✅ 동시 요청 처리: 두 번째 요청은 유니크 위반으로 실패한다
--    그때는 첫 요청이 끝날 때까지 기다렸다가 저장된 응답을 돌려준다
SELECT status, status_code, response_body
  FROM idempotency_key
 WHERE key = $1
   ;          -- ⚠️ 커밋 전 행은 다른 트랜잭션에 아예 안 보여 FOR UPDATE는 기다리지 않는다.
--                     실제 대기는 아래 INSERT가 유니크 인덱스에서 블록될 때 일어난다

-- ⚠️ '위처럼 한 트랜잭션으로 묶으면 크래시 시 전부 롤백되어 'in_progress'가 남지 않는다.
--    반대로 동시 요청에 '처리 중'을 보여 주려고 키 행을 먼저 커밋하는 2단계 설계를 택하면,
--    커밋된 채 방치된 'in_progress' 행을 주기적으로 정리해야 한다
DELETE FROM idempotency_key
 WHERE status = 'in_progress' AND created_at < now() - interval '10 minutes';

import Foundation

// 두 번째 요청에 409를 던지면 클라이언트가 '실패'로 오인해
// 사용자에게 "결제 실패"를 보여 준다 — 실제로는 성공했는데도.

/*  서버 동작 규약 (클라·서버가 합의해야 한다)

    첫 요청     → 처리하고 201 + {"orderId":"ord_1"} 저장
    같은 키 재요청 → 저장된 201 + {"orderId":"ord_1"} 를 그대로 반환
                     (헤더로 재현임을 알려도 좋다: Idempotent-Replay: true)

    ❌ 두 번째에 이미 완료된 요청의 재현에 409 Conflict → 클라가 실패로 처리한다 (완료 건은 저장된 응답을 그대로 재현해야 한다)
    ⭕ 첫 요청이 아직 처리 중일 때의 409는 표준 규약이다 → 클라는 잠시 뒤 같은 키로 다시 시도한다
    ❌ 두 번째에 200이지만 빈 바디 → 클라가 파싱에 실패한다                 */

// 클라이언트는 재현 응답도 성공으로 다룬다
func createOrder(_ body: Data, key: String) async throws -> Order {
    var request = URLRequest(url: ordersURL)
    request.httpMethod = "POST"
    request.httpBody = body
    request.setValue(key, forHTTPHeaderField: "Idempotency-Key")

    let (data, response) = try await URLSession.shared.data(for: request)
    guard let http = response as? HTTPURLResponse else { throw ClientError.invalidResponse }

    switch http.statusCode {
    case 200, 201:
        // ✅ 재현이든 최초든 동일하게 성공 처리
        if http.value(forHTTPHeaderField: "Idempotent-Replay") == "true" {
            // 필요하면 분석용으로만 기록한다 (사용자에게는 구분해 보이지 않는다)
        }
        return try JSONDecoder().decode(Order.self, from: data)

    case 409:
        // ⚠️ 서버가 이렇게 설계돼 있다면 팀과 재협의해야 한다.
        //    임시 대응: 조회로 실제 상태를 확인한다
        return try await fetchOrderByKey(key)

    case 422:
        throw ClientError.keyReusedWithDifferentBody

    default:
        throw ClientError.http(http.statusCode)
    }
}

struct Order: Decodable {}
enum ClientError: Error { case invalidResponse, keyReusedWithDifferentBody, http(Int) }
let ordersURL = URL(string: "https://api.example.com/orders")!
func fetchOrderByKey(_ key: String) async throws -> Order { Order() }

import Foundation
import CryptoKit

// 같은 키인데 본문이 다르면 그건 재시도가 아니다.
// 클라이언트 버그이거나 공격이다 — 조용히 처리하면 안 된다.

// 클라이언트: 키와 본문을 한 묶음으로 관리한다
struct IdempotentRequest {
    let key: String
    let body: Data

    /// 서버가 지문을 대조할 수 있게 함께 보낸다
    var fingerprint: String {
        Data(SHA256.hash(data: body)).base64EncodedString()
    }

    init(body: Data) {
        self.key = UUID().uuidString
        self.body = body
    }
}

func send(_ request: IdempotentRequest) async throws -> Data {
    var urlRequest = URLRequest(url: ordersURL)
    urlRequest.httpMethod = "POST"
    urlRequest.httpBody = request.body
    urlRequest.setValue(request.key, forHTTPHeaderField: "Idempotency-Key")
    urlRequest.setValue("sha-256=:\(request.fingerprint):", forHTTPHeaderField: "Content-Digest")   // RFC 9530 Structured Fields 형식

    let (data, response) = try await URLSession.shared.data(for: urlRequest)
    let code = (response as? HTTPURLResponse)?.statusCode ?? 0

    if code == 422 {
        // ✅ 서버가 "같은 키, 다른 내용"을 거부했다 — 클라 버그다. 로그를 남긴다.
        assertionFailure("멱등 키 재사용 시 본문이 달라졌다: \(request.key)")
        throw ClientError.keyReusedWithDifferentBody
    }
    return data
}

/*  서버 측 검증
      SELECT request_fingerprint FROM idempotency_key WHERE key = $1;
      → 저장된 지문과 이번 요청의 지문이 다르면 422로 거부한다

    이 검증이 잡아 주는 것
      · 클라이언트가 재시도 중 본문을 바꾼 버그
      · 키를 탈취해 다른 내용을 밀어 넣으려는 시도
      · 서로 다른 요청에 같은 키를 재사용한 실수                            */

enum ClientError: Error { case keyReusedWithDifferentBody }
let ordersURL = URL(string: "https://api.example.com/orders")!

import UIKit

// ❌ ① 클라이언트 버튼 비활성화만으로 중복을 막으려는 시도
@MainActor
final class BadCheckoutViewController: UIViewController {
    private let payButton = UIButton()

    @objc func didTapPay() {
        payButton.isEnabled = false          // 이걸로 끝이라고 생각한다
        Task { try? await charge() }
    }
    private func charge() async throws {}
}
/*  이 방어를 우회하는 경로들
      · 네트워크 타임아웃 후 자동 재시도 (UI를 안 거친다)
      · 앱 강제 종료 후 오프라인 큐 재실행
      · 리버싱한 클라이언트
      · 여러 기기에서 동시 시도
    → 버튼 비활성화는 UX 보정이지 방어선이 아니다. 진짜 방어선은 서버다.    */

// ❌ ② 재시도할 때마다 키를 새로 만든다
func retryBad(_ body: Data) async throws {
    for _ in 0..<3 {
        var r = URLRequest(url: url)
        r.httpMethod = "POST"
        r.setValue(UUID().uuidString, forHTTPHeaderField: "Idempotency-Key")  // 💥
        r.httpBody = body
        if let _ = try? await URLSession.shared.data(for: r) { return }
    }
    // 서버 입장에서는 서로 다른 3개의 요청 → 3번 결제된다
}

// ✅ 키는 요청 하나당 하나. 재시도 루프 바깥에서 만든다.
func retryGood(_ body: Data) async throws {
    let key = UUID().uuidString              // ✅ 여기, 루프 밖

    for attempt in 1...3 {
        var r = URLRequest(url: url)
        r.setValue(key, forHTTPHeaderField: "Idempotency-Key")
        r.httpBody = body
        if let _ = try? await URLSession.shared.data(for: r) { return }
        try await Task.sleep(for: .seconds(pow(2, Double(attempt))))
    }
}

// ✅ 오프라인 큐에 저장할 때도 키를 함께 저장한다
struct QueuedRequest: Codable {
    let key: String                          // ✅ 앱을 재시작해도 같은 키
    let body: Data
    let createdAt: Date
}

let url = URL(string: "https://api.example.com/payments")!

import Foundation

// 인터셉터가 모든 요청에 자동으로 키를 붙이는 구현은 위험하다.
// 재시도가 인터셉터를 다시 거치면 키가 매번 바뀐다.

// ❌ 재시도 계층 '안쪽'에서 키를 만든다
final class BadInterceptor {
    func adapt(_ request: inout URLRequest) {
        request.setValue(UUID().uuidString, forHTTPHeaderField: "Idempotency-Key")
        // 💥 재시도마다 호출되어 매번 다른 키가 붙는다
    }
}

// ✅ 키는 '요청 객체'의 일부로, 만들어질 때 한 번 정해진다
struct APIRequest {
    let endpoint: Endpoint
    let body: Data
    let idempotencyKey: String

    init(endpoint: Endpoint, body: Data) {
        self.endpoint = endpoint
        self.body = body
        // ✅ 요청 객체 하나 = 논리적 연산 하나 = 키 하나
        self.idempotencyKey = endpoint.requiresIdempotencyKey ? UUID().uuidString : ""
    }
}

// 재시도는 같은 APIRequest 객체를 반복 사용한다
final class APIClient {
    func send(_ request: APIRequest, maxAttempts: Int = 3) async throws -> Data {
        for attempt in 1...maxAttempts {
            var urlRequest = URLRequest(url: baseURL.appending(path: request.endpoint.path))
            urlRequest.httpMethod = request.endpoint.method
            urlRequest.httpBody = request.body
            if !request.idempotencyKey.isEmpty {
                urlRequest.setValue(request.idempotencyKey,
                                    forHTTPHeaderField: "Idempotency-Key")  // ✅ 항상 같다
            }

            do { return try await perform(urlRequest) }
            catch {
                guard attempt < maxAttempts else { throw error }
                try await Task.sleep(for: .seconds(pow(2, Double(attempt))))
            }
        }
        throw ClientError.exhausted
    }

    private func perform(_ r: URLRequest) async throws -> Data {
        try await URLSession.shared.data(for: r).0
    }
    private let baseURL = URL(string: "https://api.example.com")!
}

// ✅ 계층 구조로 표현하면 실수하기 어려워진다
//    [요청 생성: 키 부여]  →  [재시도 계층]  →  [전송 계층]
//         한 번만                반복                반복

struct Endpoint {
    let path: String; let method: String; let requiresIdempotencyKey: Bool
}
enum ClientError: Error { case exhausted }

import Foundation

// 서버가 키를 24시간 보관하는데 클라이언트 오프라인 큐가 3일을 버티면,
// 만료된 키로 온 재시도가 '새 연산'으로 처리되어 조용히 중복이 된다.

enum IdempotencyContract {
    /// 서버 보관 기간 (백엔드 팀과 합의한 값)
    static let serverRetention: TimeInterval = 24 * 60 * 60

    /// 클라이언트는 그보다 짧게 잡는다 — 안전 여유를 둔다
    static let clientRetryWindow: TimeInterval = 20 * 60 * 60

    static func isStillValid(_ createdAt: Date) -> Bool {
        Date().timeIntervalSince(createdAt) < clientRetryWindow
    }
}

// ✅ 오프라인 큐에서 만료된 요청은 재전송하지 않는다
struct QueuedRequest: Codable {
    let key: String
    let endpoint: String
    let body: Data
    let createdAt: Date
}

actor OfflineQueue {
    private var pending: [QueuedRequest] = []

    func flush() async {
        var remaining: [QueuedRequest] = []

        for request in pending {
            guard IdempotencyContract.isStillValid(request.createdAt) else {
                // ⚠️ 만료됨 — 그냥 보내면 중복 위험이 있다
                await handleExpired(request)
                continue
            }
            if await send(request) { continue }
            remaining.append(request)
        }
        pending = remaining
    }

    /// 만료된 요청은 '상태 조회'로 결과를 확인한 뒤 판단한다
    private func handleExpired(_ request: QueuedRequest) async {
        if let outcome = await queryOutcome(key: request.key) {
            record(outcome)                 // 이미 처리됐다
        } else {
            await notifyUser(request)       // 사용자에게 확인을 요청한다
        }
    }

    private func send(_ r: QueuedRequest) async -> Bool { true }
    private func queryOutcome(key: String) async -> String? { nil }
    private func record(_ outcome: String) {}
    private func notifyUser(_ r: QueuedRequest) async {}
}

// ⚠️ 이 값은 코드 주석이 아니라 API 문서에 명시하고 양쪽이 참조해야 한다.
//    서버가 보관 기간을 줄이면 클라도 함께 줄여야 한다.

import Foundation
import CryptoKit

// 같은 키로 다른 내용이 오는 상황은 반드시 명시적으로 거부해야 한다.
// 조용히 처리하면 첫 요청의 결과가 두 번째 요청의 응답으로 돌아간다.

struct IdempotentEnvelope: Codable {
    let key: String
    let bodyDigest: String
    let createdAt: Date

    init(key: String, body: Data) {
        self.key = key
        self.bodyDigest = Data(SHA256.hash(data: body)).base64EncodedString()
        self.createdAt = Date()
    }
}

// ✅ 클라이언트도 자기 쪽에서 한 번 검증한다 — 버그를 개발 중에 잡는다
actor IdempotencyLedger {
    private var issued: [String: IdempotentEnvelope] = [:]

    func register(key: String, body: Data) throws {
        let envelope = IdempotentEnvelope(key: key, body: body)

        if let existing = issued[key] {
            guard existing.bodyDigest == envelope.bodyDigest else {
                // 💥 같은 키인데 본문이 다르다 — 재시도 로직 버그다
                throw LedgerError.digestMismatch(key: key)
            }
            return      // 정상 재시도
        }
        issued[key] = envelope
    }

    func prune(olderThan interval: TimeInterval) {
        let cutoff = Date().addingTimeInterval(-interval)
        issued = issued.filter { $0.value.createdAt > cutoff }
    }
}

/*  서버 측 규약
      저장: (key, request_fingerprint, status_code, response_body)
      재요청 시:
        지문 일치   → 저장된 응답을 그대로 반환 (200/201)
        지문 불일치 → 422 Unprocessable Entity
                      { "error": "idempotency_key_reused_with_different_body" }

    ⚠️ 지문 계산 방식을 양쪽이 동일하게 맞춰야 한다.
       JSON 키 순서가 다르면 같은 내용이어도 지문이 달라진다.
       → 정렬된 인코딩을 쓴다                                               */
func canonicalEncode<T: Encodable>(_ value: T) throws -> Data {
    let encoder = JSONEncoder()
    encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
    return try encoder.encode(value)
}

enum LedgerError: Error { case digestMismatch(key: String) }

import Foundation
import OSLog

// ❌ ① 서버 auto-increment ID를 멱등 키로 재활용
//    · 그 ID는 서버가 요청을 '받은 뒤에' 생기므로, 첫 요청이 타임아웃되면
//      클라이언트는 키를 알 수 없다 (재시도에 쓸 값이 없다)
//    · 예측 가능해서 다른 사용자의 연산과 충돌하거나 추측될 수 있다
func badKeyFromServerID(_ orderID: Int) -> String {
    String(orderID)                      // 💥 순서가 거꾸로다
}

// ✅ 클라이언트가 요청 시작 시점에 만든 충돌 확률이 무시할 만한 값
func goodKey() -> String {
    UUID().uuidString                    // v4 — 예측 불가, 충돌 무시 가능
}

// ❌ ② 키를 URL 경로·쿼리에 넣는다
func badURL(_ key: String) -> URL {
    URL(string: "https://api.example.com/payments/\(key)")!
    // 서버 접근 로그·프록시·Referer에 평문으로 남는다.
    // 민감한 연산의 키가 노출되면 재현 공격에 쓰일 수 있다.
}

// ✅ 헤더로 보낸다
func goodRequest(_ key: String, body: Data) -> URLRequest {
    var r = URLRequest(url: URL(string: "https://api.example.com/payments")!)
    r.httpMethod = "POST"
    r.httpBody = body
    r.setValue(key, forHTTPHeaderField: "Idempotency-Key")
    return r
}

// ❌ ③ 로그에 그대로 찍는다
private let log = Logger(subsystem: "com.app", category: "payment")

func badLog(_ key: String) {
    print("결제 요청 key=\(key)")        // 시스템 로그·크래시 리포트에 남는다
}

// ✅ 마스킹하거나 private으로
func goodLog(_ key: String) {
    log.debug("결제 요청 key=\(key, privacy: .private)")
}

func masked(_ key: String) -> String {
    guard key.count > 8 else { return "***" }
    return "\(key.prefix(4))…\(key.suffix(4))"
}

// ⚠️ 크래시 리포터의 breadcrumb에 URL이 자동 수집되는 경우도 확인해야 한다

// 1) 간격·타임아웃은 단조 시계로 — 벽시계 변경에 영향 안 받음
let clock = ContinuousClock()
let start = clock.now
try await doWork()
let elapsed = start.duration(to: clock.now)   // 사용자가 시계 바꿔도 정확

// 2) 서버 시간과의 오프셋: 응답의 Date 헤더 사용 (RTT 절반 보정은 근사)
func serverOffset(from response: HTTPURLResponse, requestSent: Date) -> TimeInterval? {
    guard let dateStr = response.value(forHTTPHeaderField: "Date"),
          let serverDate = DateFormatter.httpDate.date(from: dateStr) else { return nil }
    let rtt = Date().timeIntervalSince(requestSent)
    let estimatedServerNow = serverDate.addingTimeInterval(rtt / 2)
    return estimatedServerNow.timeIntervalSince(Date())   // +면 서버가 앞섬
}

// 3) 표시용 '지금'은 로컬 시계에 오프셋을 더해 근사 — 판정은 서버가
func approxServerNow(offset: TimeInterval) -> Date { Date().addingTimeInterval(offset) }

import Foundation

// 클라이언트 시계는 사용자가 임의로 바꿀 수 있다. 신뢰 경계 밖이다.

// ❌ 클라 시계로 만료를 판정 — 시계를 되돌리면 만료가 풀린다
func isExpiredBad(_ coupon: Coupon) -> Bool {
    coupon.expiresAt < Date()            // 💥 설정에서 날짜를 바꾸면 우회된다
}

// ✅ 서버 시간을 기준으로 판정한다
actor ServerClock {
    private var offset: TimeInterval = 0     // 서버 시각 - 기기 시각
    private var lastSync: Date?

    /// 모든 응답의 Date 헤더로 오프셋을 보정한다
    func sync(from response: HTTPURLResponse) {
        guard let header = response.value(forHTTPHeaderField: "Date"),
              let serverDate = DateFormatter.rfc1123.date(from: header) else { return }
        offset = serverDate.timeIntervalSince(Date())
        lastSync = Date()
    }

    /// 보정된 '서버 기준 현재 시각'
    var now: Date { Date().addingTimeInterval(offset) }

    /// 동기화가 오래됐으면 신뢰하지 않는다
    var isReliable: Bool {
        guard let lastSync else { return false }
        return Date().timeIntervalSince(lastSync) < 3600   // ⚠️ 바로 아래 ②가 금지한 'Date 차이로 경과 측정'이다.
        //    시계를 뒤로 돌리면 음수가 되어 항상 true가 된다 — ContinuousClock 기준으로 재야 한다
    }
}

// ✅ 진짜 중요한 판정은 아예 서버가 한다
func redeemCoupon(_ code: String) async throws -> Redemption {
    // 클라는 "이 쿠폰 쓸게요"만 보내고, 유효성은 서버가 판정한다
    try await api.redeem(code)
}

// ✅ 클라 시계는 '표시'에만 쓴다
@MainActor
func displayExpiry(_ coupon: Coupon, clock: ServerClock) async -> String {
    let now = await clock.now
    let remaining = coupon.expiresAt.timeIntervalSince(now)
    return remaining > 0 ? "\(Int(remaining / 3600))시간 남음" : "만료됨"
    // ⚠️ 이 표시가 틀려도 실제 사용은 서버가 막는다
}

struct Coupon { let expiresAt: Date }
struct Redemption: Decodable {}
enum api { static func redeem(_ c: String) async throws -> Redemption { Redemption() } }
extension DateFormatter {
    static let rfc1123: DateFormatter = {
        let f = DateFormatter()
        f.locale = Locale(identifier: "en_US_POSIX")
        f.timeZone = TimeZone(identifier: "GMT")
        f.dateFormat = "EEE, dd MMM yyyy HH:mm:ss zzz"
        return f
    }()
}

import Foundation

// 벽시계(Date)는 사용자 변경·NTP 보정으로 점프하거나 되감긴다.
// 경과 시간·타임아웃·쿨다운은 되감기지 않는 시계로 재야 한다.

// ❌ Date 차이로 경과 시간 측정
func measureBad(_ work: () -> Void) -> TimeInterval {
    let start = Date()
    work()
    return Date().timeIntervalSince(start)   // 💥 중간에 시계가 바뀌면 음수도 나온다
}

// ✅ 단조 시계 — 시스템 부팅 이후 단조 증가한다
func measure(_ work: () -> Void) -> Duration {
    let start = ContinuousClock.now
    work()
    return ContinuousClock.now - start
}

// ✅ 쿨다운·레이트리밋
actor RateLimiter {
    private var lastCall: ContinuousClock.Instant?
    private let interval: Duration

    init(interval: Duration) { self.interval = interval }

    func allow() -> Bool {
        let now = ContinuousClock.now
        if let last, now - last < interval { return false }
        lastCall = now
        return true
    }
    private var last: ContinuousClock.Instant? { lastCall }
}

// ✅ 타임아웃
func withTimeout<T>(_ duration: Duration,
                    _ work: () async throws -> T) async throws -> T {
    let deadline = ContinuousClock.now + duration
    let result = try await work()
    // ⚠️ 이건 타임아웃이 아니다 — work()가 끝날 때까지 무한정 기다린 뒤 사후 검사할 뿐이라
    //    작업이 걸리면 영원히 반환하지 않고, 정상 완료된 결과도 '늦었다'며 버린다.
    //    실제 타임아웃은 withThrowingTaskGroup으로 작업과 타이머를 경쟁시키고 진 쪽을 cancelAll()한다.
    guard ContinuousClock.now < deadline else { throw TimeoutError() }
    return result
}

/*  ⚠️ 두 시계의 차이
      ContinuousClock : 기기가 잠들어 있어도 계속 흐른다 (경과 시간에 적합)
      SuspendingClock : 기기가 잠들면 멈춘다 (활성 작업 시간에 적합)
      Date            : 벽시계. 점프·되감기 가능. 절대 시각 표현용.

    ⚠️ 단조 시계는 재부팅하면 리셋된다 — 앱을 넘어 지속되는 값에는 못 쓴다.
       "다음 알림까지 3일"은 Date로, "이 요청 타임아웃 30초"는 단조 시계로.  */

struct TimeoutError: Error {}

import Foundation

// 타임존을 저장 값에 섞으면 나중에 되돌릴 수 없다.
// 항상 UTC로 저장·전송하고, 사용자에게 보여 줄 때만 변환한다.

// ✅ 전송·저장 — ISO 8601 UTC
enum WireFormat {
    static let iso8601: ISO8601DateFormatter = {
        let f = ISO8601DateFormatter()
        f.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
        f.timeZone = TimeZone(identifier: "UTC")
        return f
    }()

    static func encode(_ date: Date) -> String { iso8601.string(from: date) }
    static func decode(_ string: String) -> Date? { iso8601.date(from: string) }
}

// ✅ JSONDecoder에 일괄 적용
extension JSONDecoder {
    static let api: JSONDecoder = {
        let d = JSONDecoder()
        d.dateDecodingStrategy = .custom { decoder in
            let s = try decoder.singleValueContainer().decode(String.self)
            guard let date = WireFormat.decode(s) else {
                throw DecodingError.dataCorrupted(
                    .init(codingPath: decoder.codingPath,
                          debugDescription: "잘못된 날짜: \(s)"))
            }
            return date
        }
        return d
    }()
}

// ✅ 표시 — 그때만 사용자 타임존으로
@MainActor
enum DisplayFormat {
    static func dateTime(_ date: Date) -> String {
        date.formatted(.dateTime.year().month().day().hour().minute())
        // Locale.current·TimeZone.current가 자동 적용된다
    }

    static func relative(_ date: Date) -> String {
        date.formatted(.relative(presentation: .named))   // "3시간 전"
    }
}

// ❌ 하지 말 것
//   · 로컬 시각 문자열을 저장  ("2026-07-27 14:00")  → 어느 타임존인지 모른다
//   · 타임존을 별도 컬럼으로만 저장 → 조인·정렬이 어긋난다
//   · 날짜만 저장하고 시각을 버림 → 경계 계산이 틀어진다

// ⚠️ '날짜'가 의미 단위인 경우(생일, 기념일)와 미래의 약속(회의·알람·예약)은 예외다. 후자는 UTC 순간만 저장하면 그 사이 타임존 규칙이 바뀔 때 현지 시각이 어긋나므로 현지 시각 + IANA 타임존 ID를 함께 저장한다.
//    이건 시각이 아니라 달력상의 날이므로 타임존과 무관하게 저장한다.
struct Birthday: Codable {
    let year: Int, month: Int, day: Int      // Date가 아니라 구성요소로
}

import Foundation

// 여러 기기의 createdAt을 크기 비교해 순서를 정하면
// 기기 간 시계 차이(수 초~수 분)로 순서가 뒤집힌다.

struct Message {
    let id: UUID
    let deviceCreatedAt: Date       // 기기가 찍은 시각 — 신뢰할 수 없다
    let serverSequence: Int64?      // 서버가 부여한 순번 — 이걸 써야 한다
    let text: String
}

// ❌ 기기 시각으로 정렬
func sortBad(_ messages: [Message]) -> [Message] {
    messages.sorted { $0.deviceCreatedAt < $1.deviceCreatedAt }
    // 💥 A 기기 시계가 30초 빠르면 나중에 보낸 메시지가 앞에 온다
}

// ✅ 서버가 부여한 단조 증가 순번으로 정렬
func sort(_ messages: [Message]) -> [Message] {
    messages.sorted {
        ($0.serverSequence ?? .max, $0.id.uuidString)
            < ($1.serverSequence ?? .max, $1.id.uuidString)
    }
    // 아직 서버에 도달하지 않은 것(전송 중)은 맨 뒤로
}

// ✅ 서버가 순번을 못 주면 논리 시계를 쓴다
struct LamportClock {
    private var counter: Int64 = 0

    mutating func tick() -> Int64 {
        counter += 1
        return counter
    }

    /// 다른 기기의 이벤트를 받으면 그 값보다 크게 맞춘다
    mutating func observe(_ remote: Int64) {
        counter = max(counter, remote) + 1
    }
}

// ⚠️ 쿠폰 만료도 마찬가지다 — 클라 시계로 판정하면 우회된다
func isCouponValidBad(_ coupon: Coupon) -> Bool {
    coupon.expiresAt > Date()           // 💥 설정에서 날짜를 되돌리면 통과
}

// ✅ 사용 시도 자체를 서버가 판정하게 한다
func redeemCoupon(_ code: String) async throws -> Bool {
    try await api.redeem(code)          // 유효성은 서버 시간 기준
}

struct Coupon { let expiresAt: Date }
enum api { static func redeem(_ c: String) async throws -> Bool { true } }