10 · 파일 시스템과 I/O

// 파일 I/O 앞에 두면 메인에서 호출될 때 즉시 크래시로 잡힌다
dispatchPrecondition(condition: .notOnQueue(.main))

// ❌ 나쁨: 스크롤 콜백에서 동기 읽기 → 런루프 정지
func scrollViewDidScroll(_ sv: UIScrollView) {
    let data = try? Data(contentsOf: bigFileURL)   // 메인에서 블록
}

// ✅ 좋음: 전용 큐에서 I/O — Task.detached는 협력 풀을 벗어나지 않는다, 결과만 메인으로 hop
Task.detached(priority: .utility) {
    let data = try Data(contentsOf: bigFileURL)
    await MainActor.run { self.apply(data) }
}

import Foundation

// 파일 I/O는 page cache에 없으면 커널이 스레드를 재운다.
// 지연이 µs~수십 ms로 비결정적이라 메인에서 하면 언제든 프레임을 놓친다.

// ✅ 전용 actor로 디스크 접근을 한곳에 모은다
actor DiskStore {
    private let root: URL

    init(root: URL) { self.root = root }

    func load(_ name: String) throws -> Data {
        try Data(contentsOf: root.appendingPathComponent(name))
    }

    func save(_ data: Data, as name: String) throws {
        try data.write(to: root.appendingPathComponent(name), options: .atomic)
    }

    func delete(_ name: String) throws {
        try FileManager.default.removeItem(at: root.appendingPathComponent(name))
    }
}

// ✅ 호출부 — UI 갱신 값만 메인으로 넘어온다
@MainActor
final class NotesViewModel: ObservableObject {
    @Published private(set) var notes: [Note] = []
    private let store: DiskStore

    init(store: DiskStore) { self.store = store }

    func load() async {
        do {
            let data = try await store.load("notes.json")
            notes = try JSONDecoder().decode([Note].self, from: data)
        } catch {
            notes = []
        }
    }
}

// ⚠️ dispatchPrecondition은 -Ounchecked를 제외하면 릴리스 빌드에서도 그대로 트랩한다.
//    출시 앱이 죽어도 되는 불변식에만 쓰고, 개발 중에만 잡고 싶으면 #if DEBUG로 감싼다
func readSync(_ url: URL) throws -> Data {
    dispatchPrecondition(condition: .notOnQueue(.main))
    return try Data(contentsOf: url)
}

struct Note: Codable {}

import Foundation

// UserDefaults에 쓰면 내부적으로 plist 파일 전체를 다시 직렬화해 기록한다.
// 그 쓰기가 메인 스레드에서 동기로 일어날 수 있어 I/O가 숨어든다.

// ❌ 큰 데이터를 넣는 순간 메인에서 수백 KB~MB를 다시 쓴다
func badPersist(_ feed: [Item]) throws {
    let data = try JSONEncoder().encode(feed)
    UserDefaults.standard.set(data, forKey: "feedCache")   // 💥 큰 blob은 넣지 않는다 (앱·데몬 양쪽 메모리 상주 + 플러시마다 전체 재직렬화)
}

// ✅ 파일로 저장하고, UserDefaults에는 경로·버전 같은 작은 메타만
actor FeedCache {
    private let url: URL
    init(url: URL) { self.url = url }

    func save(_ feed: [Item]) throws {
        let data = try JSONEncoder().encode(feed)
        try data.write(to: url, options: .atomic)          // 백그라운드에서
    }

    func load() throws -> [Item] {
        try JSONDecoder().decode([Item].self, from: Data(contentsOf: url))
    }
}

func saveMetadata(_ version: Int) {
    UserDefaults.standard.set(version, forKey: "feedCacheVersion")   // ✅ 작다
}

// ✅ 현재 UserDefaults 크기를 점검해 보는 방법
func auditUserDefaults() {
    guard let id = Bundle.main.bundleIdentifier,
          let domain = UserDefaults.standard.persistentDomain(forName: id) else { return }

    let sized = domain.compactMap { key, value -> (String, Int)? in
        guard let data = try? PropertyListSerialization.data(
            fromPropertyList: [value], format: .binary, options: 0) else { return nil }
        return (key, data.count)
    }.sorted { $0.1 > $1.1 }

    for (key, bytes) in sized.prefix(10) where bytes > 4096 {
        print("⚠️ \(key): \(bytes / 1024)KB — 파일로 옮기는 것을 검토")
    }
}

struct Item: Codable {}

import UIKit

// cellForRowAt과 scrollViewDidScroll은 프레임 예산 안에서 반복 호출된다.
// 여기에 동기 I/O가 하나라도 있으면 스크롤이 즉시 끊긴다.

@MainActor
final class FeedViewController: UITableViewController {
    private var items: [Item] = []
    private var thumbnails: [UUID: UIImage] = [:]      // 미리 로드해 둔 캐시

    // ❌ 셀 구성에서 디스크를 읽는다
    func tableView(_ tv: UITableView, badCellForRowAt indexPath: IndexPath) -> UITableViewCell {
        let cell = UITableViewCell()
        let item = items[indexPath.row]
        let data = try? Data(contentsOf: item.thumbURL)      // 💥 동기 I/O
        cell.imageView?.image = data.flatMap(UIImage.init)
        return cell
    }

    // ✅ 캐시에서만 읽고, 없으면 비동기로 채운 뒤 갱신한다
    override func tableView(_ tv: UITableView,
                            cellForRowAt indexPath: IndexPath) -> UITableViewCell {
        let cell = tv.dequeueReusableCell(withIdentifier: "cell", for: indexPath)
        let item = items[indexPath.row]

        cell.imageView?.image = thumbnails[item.id]          // ✅ 메모리에서만

        if thumbnails[item.id] == nil {
            Task { await loadThumbnail(for: item, at: indexPath) }
        }
        return cell
    }

    private func loadThumbnail(for item: Item, at indexPath: IndexPath) async {
        guard let image = await DiskStore.shared.thumbnail(item.thumbURL) else { return }
        thumbnails[item.id] = image
        // 화면에 아직 보이는 셀만 갱신한다
        if tableView.indexPathsForVisibleRows?.contains(indexPath) == true {
            tableView.reloadRows(at: [indexPath], with: .none)
        }
    }

}

// ✅ 더 나은 방법: prefetch로 미리 채운다
//    (UITableViewController의 메서드가 아니라 별도 프로토콜이다 — override 아님)
extension FeedViewController: UITableViewDataSourcePrefetching {
    func tableView(_ tv: UITableView, prefetchRowsAt paths: [IndexPath]) {
        for p in paths where thumbnails[items[p.row].id] == nil {
            Task { await loadThumbnail(for: items[p.row], at: p) }
        }
    }
}

struct Item { let id: UUID; let thumbURL: URL }
actor DiskStore {
    static let shared = DiskStore()
    func thumbnail(_ url: URL) -> UIImage? { nil }
}

// ❌ 파일 크기만큼 힙에 상주
let all = try Data(contentsOf: url)

// ✅ 안전하면 메모리 매핑 — 접근한 페이지만 올라옴
let mapped = try Data(contentsOf: url, options: .mappedIfSafe)

// ✅ 청크 스트리밍 — 상수 메모리로 처리
let handle = try FileHandle(forReadingFrom: url)
defer { try? handle.close() }
while let chunk = try handle.read(upToCount: 1 << 20), !chunk.isEmpty {
    process(chunk)                 // 1MB씩만 메모리에
}

// 남은 메모리 예산(바이트) 확인
let budget = os_proc_available_memory()

import Foundation

// Data(contentsOf:)는 파일 크기만큼 익명 dirty 메모리를 잡는다.
// iOS엔 스왑이 없으므로 상한을 넘는 순간 jetsam이다.

// ❌ 500MB 비디오를 통째로
func loadBad(_ url: URL) throws -> Data {
    try Data(contentsOf: url)
}

// ✅ ① 순차 처리라면 청크 스트리밍 — 상수 메모리
func processStreaming(_ url: URL, chunkSize: Int = 1 << 20) throws {
    let handle = try FileHandle(forReadingFrom: url)
    defer { try? handle.close() }

    while let chunk = try handle.read(upToCount: chunkSize), !chunk.isEmpty {
        process(chunk)                      // 항상 1MB만 메모리에
    }
}

// ✅ ② 임의 접근·일부만 읽는다면 매핑
func readHeader(_ url: URL) throws -> Data {
    let mapped = try Data(contentsOf: url, options: .mappedIfSafe)
    return Data(mapped.prefix(4096))        // 이 페이지들만 물리 메모리로
}

// ✅ ③ 해시·업로드처럼 전체를 훑되 담아 둘 필요가 없으면 증분 처리
import CryptoKit

func sha256(of url: URL) throws -> String {
    var hasher = SHA256()
    let handle = try FileHandle(forReadingFrom: url)
    defer { try? handle.close() }
    while let chunk = try handle.read(upToCount: 1 << 20), !chunk.isEmpty {
        hasher.update(data: chunk)
    }
    return Data(hasher.finalize()).base64EncodedString()
}

// ✅ ④ 업로드는 파일 자체를 넘긴다 — 메모리에 올리지 않는다
func upload(_ url: URL, to endpoint: URL) async throws {
    var request = URLRequest(url: endpoint)
    request.httpMethod = "PUT"
    _ = try await URLSession.shared.upload(for: request, fromFile: url)
}

func process(_ chunk: Data) {}

import Foundation

// JSONDecoder는 전체 Data를 요구한다. 200MB JSON이면 원본 200MB +
// 파싱 중 중간 표현까지 메모리에 올라온다.

// ❌ 통째로 디코딩
func decodeBad(_ url: URL) throws -> [Record] {
    let data = try Data(contentsOf: url)
    return try JSONDecoder().decode([Record].self, from: data)
}

// ✅ ① 포맷을 JSON Lines로 바꾼다 — 한 줄이 한 레코드
//    {"id":1,"name":"a"}
//    {"id":2,"name":"b"}
func decodeLines(_ url: URL) async throws -> Int {
    var count = 0
    let decoder = JSONDecoder()

    for try await line in url.lines {                 // ✅ 한 줄씩 스트리밍
        guard !line.isEmpty else { continue }
        let record = try decoder.decode(Record.self, from: Data(line.utf8))
        try insert(record)
        count += 1

        if count % 1000 == 0 { try Task.checkCancellation() }
    }
    return count
}

// ✅ ② 포맷을 바꿀 수 없으면 매핑 + 증분 파싱
func decodeMapped(_ url: URL) throws -> [Record] {
    let mapped = try Data(contentsOf: url, options: .mappedIfSafe)
    // 매핑이라 clean 페이지 → 압박 시 커널이 회수할 수 있다
    return try JSONDecoder().decode([Record].self, from: mapped)
    // ⚠️ 그래도 파싱 결과 객체는 dirty로 쌓인다 — 근본 해결은 아니다
}

// ✅ ③ 애초에 서버에 페이지네이션을 요청한다 (가장 확실한 해법)
func fetchPaged() async throws {
    var cursor: String?
    repeat {
        let page = try await api.records(after: cursor, limit: 500)
        for r in page.items { try insert(r) }
        cursor = page.next
    } while cursor != nil
}

struct Record: Decodable { let id: Int }
struct Page: Decodable { let items: [Record]; let next: String? }
enum api {
    static func records(after: String?, limit: Int) async throws -> Page {
        Page(items: [], next: nil)
    }
}
func insert(_ r: Record) throws {}

import Foundation

// mmap한 영역을 읽는 도중 파일이 잘리거나 사라지면 SIGBUS로 즉사한다.
// try/catch로 못 잡는다 — 시그널이지 Swift 에러가 아니다.

// ❌ 위험한 위치
func riskyMapping() throws {
    // 다른 프로세스가 언제든 바꿀 수 있는 App Group 공유 파일
    let shared = FileManager.default
        .containerURL(forSecurityApplicationGroupIdentifier: "group.com.app")!
        .appendingPathComponent("shared.bin")
    _ = try Data(contentsOf: shared, options: .mappedIfSafe)   // 💥 확장이 truncate하면 SIGBUS

    // 네트워크 볼륨·외부 저장소도 마찬가지
}

// ✅ 안전한 위치: 내 앱 컨테이너 안이고, 내가 수명을 통제하는 파일
func safeMapping() throws -> Data {
    let docs = try FileManager.default.url(
        for: .documentDirectory, in: .userDomainMask, appropriateFor: nil, create: true)
    let url = docs.appendingPathComponent("dictionary.bin")   // 앱 번들에서 복사해 둔 것
    return try Data(contentsOf: url, options: .mappedIfSafe)
}

// ✅ 앱 번들 리소스는 가장 안전하다 — 읽기 전용이고 바뀌지 않는다
func mapBundleResource() throws -> Data? {
    guard let url = Bundle.main.url(forResource: "dictionary", withExtension: "bin")
    else { return nil }
    return try Data(contentsOf: url, options: .mappedIfSafe)
}

// ✅ 공유 파일을 꼭 매핑해야 하면 '스냅샷 사본'을 만들어 그걸 매핑한다
func mapSnapshot(of shared: URL) throws -> Data {
    let temp = FileManager.default.temporaryDirectory
        .appendingPathComponent(UUID().uuidString)
    try FileManager.default.copyItem(at: shared, to: temp)     // 내가 통제하는 사본
    defer { /* 사용 후 정리 */ }
    return try Data(contentsOf: temp, options: .mappedIfSafe)
}

// ⚠️ .mappedIfSafe는 "안전할 때만 매핑"이라 위험 판단이 되면 그냥 전체를 읽는다.
//    즉 매핑이 보장되지 않는다 — 메모리 절감을 전제로 설계하면 안 된다.

let fm = FileManager.default

let docs   = try fm.url(for: .documentDirectory,          in: .userDomainMask, appropriateFor: nil, create: false)
let appSup = try fm.url(for: .applicationSupportDirectory, in: .userDomainMask, appropriateFor: nil, create: true)
let caches = try fm.url(for: .cachesDirectory,            in: .userDomainMask, appropriateFor: nil, create: false)
let tmp    = fm.temporaryDirectory

// Documents 안에 재생성 가능한 큰 파일을 둘 때: 백업에서 제외 (미설정 시 리젝 사유)
var url = docs.appendingPathComponent("cache.bin")
var values = URLResourceValues()
values.isExcludedFromBackup = true
try url.setResourceValues(values)

import Foundation

// 사용자가 만든 것도 아니고, 다시 받을 수도 없는 '앱의 살림살이'가 여기 간다.
// 백업되지만 파일 앱에는 보이지 않는다.

enum AppPaths {
    private static let fm = FileManager.default

    /// SQLite·Core Data 스토어, 앱 내부 상태
    static var applicationSupport: URL {
        get throws {
            let base = try fm.url(for: .applicationSupportDirectory,
                                  in: .userDomainMask, appropriateFor: nil, create: true)
            // ⚠️ Application Support는 앱별 하위 폴더를 직접 만드는 게 관례다
            let dir = base.appendingPathComponent(
                Bundle.main.bundleIdentifier ?? "app", isDirectory: true)
            if !fm.fileExists(atPath: dir.path) {
                try fm.createDirectory(at: dir, withIntermediateDirectories: true)
            }
            return dir
        }
    }

    static var databaseURL: URL {
        get throws { try applicationSupport.appendingPathComponent("store.sqlite") }
    }
}

// Core Data 스토어 위치 지정
import CoreData

func makeContainer() throws -> NSPersistentContainer {
    let container = NSPersistentContainer(name: "Model")
    let description = NSPersistentStoreDescription(url: try AppPaths.databaseURL)
    container.persistentStoreDescriptions = [description]
    container.loadPersistentStores { _, error in precondition(error == nil) }
    return container
}

// ⚠️ 기본값으로 두면 Core Data는 Application Support에 넣는다 —
//    이미 올바른 위치라 굳이 옮길 필요는 없다. 명시는 위치를 통제하고 싶을 때.

import Foundation

// Caches는 백업에서 자동 제외되고, 저장 공간이 부족하면 OS가 지운다.
// "없어지면 다시 만들면 되는 것"만 여기 둔다.

actor ImageDiskCache {
    private let dir: URL
    private let maxBytes: Int

    init(maxBytes: Int = 200 * 1024 * 1024) throws {
        let caches = try FileManager.default.url(
            for: .cachesDirectory, in: .userDomainMask, appropriateFor: nil, create: true)
        dir = caches.appendingPathComponent("images", isDirectory: true)
        try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
        self.maxBytes = maxBytes
    }

    func store(_ data: Data, for key: String) throws {
        try data.write(to: dir.appendingPathComponent(key), options: .atomic)
    }

    func load(for key: String) -> Data? {
        try? Data(contentsOf: dir.appendingPathComponent(key))
    }

    // ✅ OS가 지우기 전에 스스로 상한을 지킨다
    func trim() throws {
        let keys: Set<URLResourceKey> = [.contentAccessDateKey, .fileSizeKey]
        let files = try FileManager.default.contentsOfDirectory(
            at: dir, includingPropertiesForKeys: Array(keys))

        var entries = try files.map { url -> (URL, Date, Int) in
            let v = try url.resourceValues(forKeys: keys)
            return (url, v.contentAccessDate ?? .distantPast, v.fileSize ?? 0)
        }
        var total = entries.reduce(0) { $0 + $1.2 }
        entries.sort { $0.1 < $1.1 }                       // LRU — 오래된 것부터

        for (url, _, size) in entries where total > maxBytes {
            try FileManager.default.removeItem(at: url)
            total -= size
        }
    }
}

// ⚠️ "Caches니까 영구적"이라는 가정은 틀렸다. 항상 "없으면 다시 만든다" 경로가 있어야 한다.

import Foundation

// tmp와 Caches는 OS가 언제든 지울 수 있다. 사용자가 만든 유일본을 여기 두면
// 어느 날 조용히 사라지고 복구할 방법이 없다.

// ❌ 작성 중인 글을 tmp에
func saveDraftBad(_ text: String) throws {
    let url = FileManager.default.temporaryDirectory.appendingPathComponent("draft.txt")
    try text.write(to: url, atomically: true, encoding: .utf8)   // 💥 사라질 수 있다
}

// ✅ 사용자 데이터는 Documents (백업 + 파일 앱 노출)
func saveDraft(_ text: String) throws {
    let docs = try FileManager.default.url(
        for: .documentDirectory, in: .userDomainMask, appropriateFor: nil, create: true)
    try text.write(to: docs.appendingPathComponent("draft.txt"),
                   atomically: true, encoding: .utf8)
}

// ✅ 사용자에게 안 보여야 하지만 유일본이면 Application Support
func saveInternalState(_ data: Data) throws {
    let dir = try AppPaths.applicationSupport
    try data.write(to: dir.appendingPathComponent("state.bin"), options: .atomic)
}

// ✅ tmp의 올바른 용도: 작업 중간 산출물. 쓰고 나면 직접 지운다.
func convertVideo(_ input: URL) throws -> Data {
    let temp = FileManager.default.temporaryDirectory
        .appendingPathComponent(UUID().uuidString + ".mp4")
    defer { try? FileManager.default.removeItem(at: temp) }      // ✅ 직접 정리

    try transcode(input, to: temp)
    return try Data(contentsOf: temp)
}

// 판단표
//   사용자가 만들었고 유일본            → Documents
//   앱 내부 영구 상태(DB 등)            → Application Support
//   다시 받거나 만들 수 있음            → Caches
//   지금 이 작업에만 필요               → tmp (직접 삭제)

enum AppPaths {
    static var applicationSupport: URL {
        get throws {
            try FileManager.default.url(for: .applicationSupportDirectory,
                                        in: .userDomainMask, appropriateFor: nil, create: true)
        }
    }
}
func transcode(_ input: URL, to output: URL) throws {}

func atomicWriteDurable(_ data: Data, to dest: URL) throws {
    let dir = dest.deletingLastPathComponent()
    let tmp = dir.appendingPathComponent(".tmp-" + UUID().uuidString)  // 반드시 같은 볼륨

    // 1) tmp 파일에 전부 write
    FileManager.default.createFile(atPath: tmp.path, contents: nil)
    let fh = try FileHandle(forWritingTo: tmp)
    try fh.write(contentsOf: data)

    // 2) 디스크 매체까지 강제 flush — 전원 손실 대비 (fsync보다 강한 F_FULLFSYNC)
    if fcntl(fh.fileDescriptor, F_FULLFSYNC) == -1 { throw POSIXError(.EIO) }
    try fh.close()

    // 3) 교체: replaceItemAt은 원본 메타데이터를 보존해 주지만 Apple이 '원자성'을 명시적으로
    //    보장하지는 않는다(문서 표현은 '데이터 손실이 없도록'까지다).
    //    문서화된 원자성이 꼭 필요하면 같은 볼륨에서 rename(tmp.path, dest.path)을 직접 부른다.
    //    (교체 자체의 지속성까지 필요하면 상위 디렉터리 fd도 fsync)
    _ = try FileManager.default.replaceItemAt(dest, withItemAt: tmp)
}

import Foundation

// 두 성질을 구분해야 한다.
//   원자성(atomicity) : 반쪽 파일이 관찰되지 않는다 → rename으로 달성
//   지속성(durability): 전원이 나가도 남아 있다      → fsync로 달성

// ✅ ① 대부분의 경우 — 앱 종료(SIGKILL)까지는 이걸로 충분하다
func saveSettings(_ data: Data, to url: URL) throws {
    try data.write(to: url, options: .atomic)
    // 내부적으로 aux 파일에 쓴 뒤 rename한다
}

// ✅ ② 금융·과금처럼 손실이 치명적이면 매체까지 강제로 내린다
func saveDurably(_ data: Data, to dest: URL) throws {
    let dir = dest.deletingLastPathComponent()
    let temp = dir.appendingPathComponent(".tmp-" + UUID().uuidString)   // 같은 볼륨

    FileManager.default.createFile(atPath: temp.path, contents: nil)
    let handle = try FileHandle(forWritingTo: temp)

    try handle.write(contentsOf: data)

    // fsync는 '디스크에 보냈다'까지, F_FULLFSYNC는 '매체에 실제로 기록됐다'까지
    guard fcntl(handle.fileDescriptor, F_FULLFSYNC) != -1 else {
        try? handle.close()
        throw POSIXError(.EIO)
    }
    try handle.close()

    // replaceItemAt은 원본의 권한·확장속성·리소스 포크를 보존한다
    _ = try FileManager.default.replaceItemAt(dest, withItemAt: temp)
}

// ⚠️ F_FULLFSYNC는 느리다(수십~수백 ms). 자주 부르면 체감 성능이 무너진다.
//    "이 데이터를 잃으면 사용자가 돈을 잃는가?"가 기준이다.

// ✅ 성능과 안전의 절충: 평소엔 .atomic, 결정적 시점에만 fsync
func saveWithCheckpoint(_ data: Data, to url: URL, isCritical: Bool) throws {
    if isCritical { try saveDurably(data, to: url) }
    else { try data.write(to: url, options: .atomic) }
}

import Foundation
import SQLite3

// 파일 단위 원자적 쓰기는 '한 파일'만 보장한다.
// A와 B가 함께 맞아야 하는데 A만 쓰고 죽으면 여전히 깨진 상태다.

// ❌ 세 파일을 각각 원자적으로 쓴다 — 파일 간 일관성은 없다
func saveBad(_ order: Order, _ payment: Payment, _ receipt: Receipt) throws {
    try JSONEncoder().encode(order).write(to: orderURL, options: .atomic)
    // 💥 여기서 죽으면 주문만 있고 결제·영수증은 없다
    try JSONEncoder().encode(payment).write(to: paymentURL, options: .atomic)
    try JSONEncoder().encode(receipt).write(to: receiptURL, options: .atomic)
}

// ✅ ① SQLite 트랜잭션으로 묶는다
func saveInTransaction(_ db: OpaquePointer,
                       _ order: Order, _ payment: Payment) throws {
    sqlite3_exec(db, "BEGIN IMMEDIATE;", nil, nil, nil)
    do {
        try insertOrder(db, order)
        try insertPayment(db, payment)
        sqlite3_exec(db, "COMMIT;", nil, nil, nil)      // ✅ 전부 반영되거나
    } catch {
        sqlite3_exec(db, "ROLLBACK;", nil, nil, nil)    //    전부 무효
        throw error
    }
}

// ✅ ② Core Data라면 하나의 save()
import CoreData
func saveWithCoreData(_ ctx: NSManagedObjectContext) throws {
    // 여러 객체를 만들고
    try ctx.save()                                       // ✅ 한 번의 트랜잭션
}

// ✅ ③ DB를 못 쓰는 상황이면 '디렉터리 통째 교체'로 흉내낼 수 있다
func saveDirectoryAtomically(_ files: [String: Data], to dest: URL) throws {
    let fm = FileManager.default
    let staging = dest.deletingLastPathComponent()
        .appendingPathComponent(".staging-" + UUID().uuidString)
    try fm.createDirectory(at: staging, withIntermediateDirectories: true)

    for (name, data) in files {
        try data.write(to: staging.appendingPathComponent(name), options: .atomic)
    }
    // 디렉터리 전체를 한 번에 교체 — 중간 상태가 관찰되지 않는다
    _ = try fm.replaceItemAt(dest, withItemAt: staging)
}

struct Order: Codable {}; struct Payment: Codable {}; struct Receipt: Codable {}
let orderURL = URL(fileURLWithPath: "/o"); let paymentURL = URL(fileURLWithPath: "/p")
let receiptURL = URL(fileURLWithPath: "/r")
func insertOrder(_ db: OpaquePointer, _ o: Order) throws {}
func insertPayment(_ db: OpaquePointer, _ p: Payment) throws {}

import Foundation

// .atomic은 임시 파일에 전부 쓴 뒤 교체한다.
// 1GB 파일이면 순간적으로 2GB의 디스크가 필요하고, 쓰기량도 2배다.

// ❌ 큰 파일을 매번 통째로 원자적으로
func appendLogBad(_ line: String, to url: URL) throws {
    var existing = try Data(contentsOf: url)        // 전체 읽기
    existing.append(Data(line.utf8))
    try existing.write(to: url, options: .atomic)   // 💥 전체 다시 쓰기 + 사본
}

// ✅ ① append는 그냥 이어 쓴다 — 원자성이 필요 없는 연산이다
func appendLog(_ line: String, to url: URL) throws {
    let handle = try FileHandle(forWritingTo: url)
    defer { try? handle.close() }
    try handle.seekToEnd()
    try handle.write(contentsOf: Data((line + "\n").utf8))
}

// ✅ ② 부분 갱신이 잦으면 DB로 옮긴다 — 애초에 이런 용도로 만들어진 것이다

// ✅ ③ 큰 파일을 꼭 교체해야 하면 공간을 먼저 확인한다
func hasSpace(for bytes: Int, at url: URL) throws -> Bool {
    let values = try url.resourceValues(forKeys: [.volumeAvailableCapacityForImportantUsageKey])
    let available = values.volumeAvailableCapacityForImportantUsage ?? 0
    return available > Int64(bytes) * 2      // 사본 공간까지
}

// ⚠️ .atomic의 또 다른 부작용: 새 파일로 교체되므로 원본의 권한·확장속성·
//    파일 보호 클래스가 초기화될 수 있다.
// ✅ 그걸 보존하려면 replaceItemAt을 쓴다
func replacePreservingAttributes(_ data: Data, at dest: URL) throws {
    let temp = dest.deletingLastPathComponent()
        .appendingPathComponent(".tmp-" + UUID().uuidString)
    try data.write(to: temp, options: .atomic)
    _ = try FileManager.default.replaceItemAt(dest, withItemAt: temp)
}

// 내부적으로 aux 파일에 write 후 rename — 반쪽 파일이 관찰되지 않는다
try data.write(to: url, options: .atomic)

// 문자열/레거시 컬렉션도 동일한 원자적 옵션 제공
try text.write(to: url, atomically: true, encoding: .utf8)

// 주의: .atomic 은 '원자성'만 보장.
// 전원 손실 후 유지(지속성)는 별개 → Q4의 F_FULLFSYNC가 필요.

import Foundation

// 반쪽 파일이 남으면 다음 실행에서 파싱이 실패하고, 최악의 경우
// "설정이 전부 초기화됨"으로 사용자에게 보인다. .atomic이 이걸 막는다.

// ✅ Data
func save(_ data: Data, to url: URL) throws {
    try data.write(to: url, options: .atomic)
}

// ✅ String
func save(_ text: String, to url: URL) throws {
    try text.write(to: url, atomically: true, encoding: .utf8)
}

// ✅ Codable 직렬화 결과
func save<T: Encodable>(_ value: T, to url: URL) throws {
    let encoder = JSONEncoder()
    encoder.outputFormatting = [.sortedKeys]      // 재현 가능한 출력
    try encoder.encode(value).write(to: url, options: .atomic)
}

// ✅ PropertyList
func savePlist<T: Encodable>(_ value: T, to url: URL) throws {
    let encoder = PropertyListEncoder()
    encoder.outputFormat = .binary
    try encoder.encode(value).write(to: url, options: .atomic)
}

// ✅ 읽기 쪽도 손상에 대비한다 — 원자적 쓰기여도 디스크 오류는 있을 수 있다
func load<T: Decodable>(_ type: T.Type, from url: URL) -> T? {
    guard let data = try? Data(contentsOf: url) else { return nil }
    do {
        return try JSONDecoder().decode(type, from: data)
    } catch {
        // 손상된 파일은 치우고 기본값으로 시작한다
        try? FileManager.default.moveItem(
            at: url, to: url.appendingPathExtension("corrupt"))
        return nil
    }
}

// ⚠️ atomically: true는 목적지와 같은 디렉터리에 aux 파일을 만든다.
//    그래서 목적지 볼륨과 무관하게 원자성이 보장된다(cross-device 문제 없음).

import Foundation

// 원자적 교체는 '새 파일을 만들어 이름을 바꾸는' 것이다.
// 이미 열어 둔 파일 디스크립터나 매핑은 옛 파일(inode)을 계속 본다.

func demonstrateStaleView() throws {
    let url = URL(fileURLWithPath: NSTemporaryDirectory() + "data.bin")
    try Data("버전1".utf8).write(to: url, options: .atomic)

    // 매핑을 잡아 둔다
    let mapped = try Data(contentsOf: url, options: .mappedIfSafe)
    print(String(data: mapped, encoding: .utf8) ?? "")      // "버전1"

    // 다른 곳에서 원자적으로 교체
    try Data("버전2".utf8).write(to: url, options: .atomic)

    print(String(data: mapped, encoding: .utf8) ?? "")      // ⚠️ 여전히 "버전1"
    // 파일 시스템 상의 이름은 새 inode를 가리키지만,
    // mapped는 옛 inode를 붙들고 있다.

    // ✅ 새 내용을 보려면 다시 연다
    let remapped = try Data(contentsOf: url, options: .mappedIfSafe)
    print(String(data: remapped, encoding: .utf8) ?? "")    // "버전2"
}

// ✅ 실무 대응 ① 변경 감시를 붙여 다시 연다
func watchAndRemap(_ url: URL,
                   onChange: @escaping () -> Void) -> DispatchSourceFileSystemObject? {
    let fd = open(url.path, O_EVTONLY)
    guard fd >= 0 else { return nil }
    let source = DispatchSource.makeFileSystemObjectSource(
        fileDescriptor: fd, eventMask: [.write, .rename, .delete], queue: .main)
    source.setEventHandler { onChange() }        // 여기서 다시 매핑한다
    source.setCancelHandler { close(fd) }
    source.resume()
    return source
}

// ✅ 대응 ② 애초에 교체 대신 '같은 파일 안에서 갱신'하는 구조를 쓴다 (DB)

// ⚠️ 이 성질이 이득이 되기도 한다: 읽는 쪽은 교체 중에도 일관된 옛 버전을
//    끝까지 볼 수 있다. 그래서 rename 방식이 "반쪽을 보지 않는다"를 보장한다.

import Foundation

// 원자적 쓰기는 매번 전체 복사다. 큰 파일을 초당 여러 번 쓰면
// write amplification으로 디스크 대역폭과 플래시 수명을 태운다.

// ❌ 100MB 상태 파일을 1초마다 통째로
final class BadStateStore {
    private var state: [String: Data] = [:]

    func update(_ key: String, _ value: Data) throws {
        state[key] = value
        try PropertyListSerialization
            .data(fromPropertyList: state, format: .binary, options: 0)
            .write(to: url, options: .atomic)      // 💥 매번 100MB 쓰기
    }
    private let url = URL(fileURLWithPath: "/state.plist")
}

// ✅ ① 변경분만 append하고 주기적으로 압축한다 (로그 구조)
final class AppendLogStore {
    private let handle: FileHandle

    init(url: URL) throws {
        if !FileManager.default.fileExists(atPath: url.path) {
            FileManager.default.createFile(atPath: url.path, contents: nil)
        }
        handle = try FileHandle(forWritingTo: url)
        try handle.seekToEnd()
    }

    func append(_ record: Data) throws {
        var length = UInt32(record.count).littleEndian
        try handle.write(contentsOf: Data(bytes: &length, count: 4))
        try handle.write(contentsOf: record)       // ✅ 변경분만
    }

    /// 로그가 길어지면 현재 상태를 스냅샷으로 압축한다 (가끔만)
    func compact(_ snapshot: Data, to url: URL) throws {
        try snapshot.write(to: url, options: .atomic)
    }
}

// ✅ ② 애초에 이런 요구면 SQLite가 정답이다 —
//    부분 갱신·트랜잭션·크래시 복구가 전부 해결된다

// ✅ ③ 쓰기를 디바운스해 빈도를 줄인다
@MainActor
final class DebouncedSaver {
    private var task: Task<Void, Never>?

    func scheduleSave(_ save: @escaping () throws -> Void) {
        task?.cancel()
        task = Task {
            try? await Task.sleep(for: .seconds(2))
            guard !Task.isCancelled else { return }
            try? save()
        }
    }
}