Networking: URLSession, Network Framework and ATS

// Packages/FieldNotesKit/Sources/FieldNotesServices/Networking/RemoteNote.swift
import Foundation
import FieldNotesModel

public struct RemoteNote: Codable, Sendable, Identifiable {
    public var id: UUID
    public var title: String
    public var body: String
    public var createdAt: Date
    public var updatedAt: Date
    public var notebookID: UUID?
    public var tags: [String]
    public var isPinned: Bool
    public var location: NoteLocation?

    public init(_ note: Note, updatedAt: Date = .now) {
        id = note.id; title = note.title; body = note.body; createdAt = note.createdAt
        self.updatedAt = updatedAt; notebookID = note.notebookID; tags = note.tags
        isPinned = note.isPinned; location = note.location
    }

    public var note: Note {
        Note(id: id, title: title, body: body, createdAt: createdAt, notebookID: notebookID,
             tags: tags, isPinned: isPinned, location: location)
    }
}

// Packages/FieldNotesKit/Sources/FieldNotesServices/Networking/NotesAPIClient.swift
import Foundation
import FieldNotesModel

public enum NotesAPIError: Error, Sendable {
    case invalidResponse
    case unauthorized                       // 401: the token expired or was revoked
    case http(status: Int, retryAfter: Duration?)
}

public actor NotesAPIClient {
    public static let productionBaseURL = URL(string: "https://api.fieldnotes.example.com")!

    private let baseURL: URL
    private let session: URLSession
    private let tokenProvider: @Sendable () async throws -> String?
    private let decoder: JSONDecoder
    private let encoder: JSONEncoder

    public init(baseURL: URL = NotesAPIClient.productionBaseURL,
                session: URLSession = .shared,
                tokenProvider: @escaping @Sendable () async throws -> String? = { nil }) {
        self.baseURL = baseURL
        self.session = session
        self.tokenProvider = tokenProvider
        decoder = JSONDecoder()
        decoder.keyDecodingStrategy = .convertFromSnakeCase
        decoder.dateDecodingStrategy = .iso8601
        encoder = JSONEncoder()
        encoder.keyEncodingStrategy = .convertToSnakeCase
        encoder.dateEncodingStrategy = .iso8601
    }

    /// GET /v1/notes?since=<date>: the notes changed on the server since the last sync.
    public func notes(since date: Date?) async throws -> [RemoteNote] {
        var components = URLComponents(url: baseURL.appending(path: "v1/notes"), resolvingAgainstBaseURL: false)!
        if let date {
            components.queryItems = [URLQueryItem(name: "since", value: date.ISO8601Format())]
        }
        let request = try await authorizedRequest(for: components.url!)
        let (data, response) = try await withRetries { try await self.session.data(for: request) }
        try Self.validate(response)
        return try decoder.decode([RemoteNote].self, from: data)
    }

    // MARK: - Helpers

    private func authorizedRequest(for url: URL, method: String = "GET") async throws -> URLRequest {
        var request = URLRequest(url: url)
        request.httpMethod = method
        request.setValue("application/json", forHTTPHeaderField: "Accept")
        if let token = try await tokenProvider() {
            request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
        }
        return request
    }

    private static func validate(_ response: URLResponse) throws {
        guard let http = response as? HTTPURLResponse else { throw NotesAPIError.invalidResponse }
        switch http.statusCode {
        case 200..<300:
            return
        case 401:
            throw NotesAPIError.unauthorized
        default:
            let retryAfter = http.value(forHTTPHeaderField: "Retry-After")
                .flatMap(Int.init).map { Duration.seconds($0) }
            throw NotesAPIError.http(status: http.statusCode, retryAfter: retryAfter)
        }
    }
}

// NotesAPIClient.swift (continued)
extension NotesAPIClient {
    public struct ServiceStatus: Decodable, Sendable {
        public var isAvailable: Bool
        public var message: String?
    }

    /// GET /status: no token, no retries; a quick check for the settings screen.
    public func serviceStatus() async throws -> ServiceStatus {
        let (data, response) = try await session.data(from: baseURL.appending(path: "status"))
        try Self.validate(response)
        return try decoder.decode(ServiceStatus.self, from: data)
    }
}

// NotesAPIClient.swift (continued)
extension NotesAPIClient {
    /// PUT /v1/notes: create or replace a batch of notes. Idempotent, so it's safe to retry.
    public func push(_ notes: [RemoteNote]) async throws {
        var request = try await authorizedRequest(for: baseURL.appending(path: "v1/notes"), method: "PUT")
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        let body = try encoder.encode(notes)
        let (_, response) = try await withRetries { [request] in
            try await self.session.upload(for: request, from: body)
        }
        try Self.validate(response)
    }
}

// NotesAPIClient.swift (continued)
extension NotesAPIClient {
    /// GET /v1/notes/changes: a long-lived NDJSON stream, one RemoteNote per line.
    /// Returns when the server closes the stream; throws CancellationError when the caller's task is cancelled.
    public func followChanges(_ apply: @Sendable (RemoteNote) async -> Void) async throws {
        let request = try await authorizedRequest(for: baseURL.appending(path: "v1/notes/changes"))
        let (bytes, response) = try await session.bytes(for: request)
        try Self.validate(response)
        for try await line in bytes.lines where !line.isEmpty {
            let change = try decoder.decode(RemoteNote.self, from: Data(line.utf8))
            await apply(change)
        }
    }
}

// NotesAPIClient.swift (continued)
extension NotesAPIClient {
    /// An authorized GET for one attachment; also used by AttachmentDownloader's background tasks.
    public func downloadRequest(for attachment: PhotoAttachment) async throws -> URLRequest {
        try await authorizedRequest(for: baseURL.appending(path: "v1/attachments/\(attachment.id.uuidString)"))
    }

    /// Downloads one attachment now, while the person waits, into the attachments folder.
    public func downloadNow(_ attachment: PhotoAttachment) async throws -> URL {
        let request = try await downloadRequest(for: attachment)
        let (temporaryURL, response) = try await session.download(for: request)
        try Self.validate(response)
        try FieldNotesPaths.prepareAttachmentsDirectory()
        let destination = FieldNotesPaths.attachments.appending(path: attachment.fileName)
        try? FileManager.default.removeItem(at: destination)
        try FileManager.default.moveItem(at: temporaryURL, to: destination)
        return destination
    }
}

// NotesAPIClient.swift (continued)
extension NotesAPIClient {
    func withRetries<T: Sendable>(maxAttempts: Int = 3,
                                  _ operation: @Sendable () async throws -> T) async throws -> T {
        var attempt = 1
        while true {
            do {
                return try await operation()
            } catch {
                guard attempt < maxAttempts, let delay = Self.retryDelay(for: error, attempt: attempt) else {
                    throw error
                }
                try await Task.sleep(for: delay)   // throws CancellationError if the caller is cancelled
                attempt += 1
            }
        }
    }

    private static func retryDelay(for error: any Error, attempt: Int) -> Duration? {
        let backoff = Duration.milliseconds(500 * (1 << (attempt - 1)) + Int.random(in: 0...250))
        switch error {
        case is CancellationError:
            return nil
        case let urlError as URLError:
            switch urlError.code {
            case .timedOut, .networkConnectionLost, .notConnectedToInternet, .cannotConnectToHost:
                return backoff
            default:
                return nil                  // .cancelled, ATS and TLS errors, bad URLs: don't retry
            }
        case let apiError as NotesAPIError:
            guard case .http(let status, let retryAfter) = apiError, status == 429 || status >= 500 else {
                return nil                  // 401 and other 4xx: retrying won't help
            }
            return retryAfter ?? backoff
        default:
            return nil
        }
    }
}

// FieldNotes/Environment/NotesAPIClient+Environment.swift
import SwiftUI
import FieldNotesServices

extension EnvironmentValues {
    @Entry var notesAPIClient = NotesAPIClient()
}

// FieldNotes/Views/NoteList.swift (excerpt)
import SwiftUI
import FieldNotesModel
import FieldNotesServices

struct NoteList: View {
    @Environment(NoteStore.self) private var store
    @Environment(\.notesAPIClient) private var notesAPIClient
    @AppStorage("lastRemoteSync") private var lastRemoteSync = Date.distantPast
    @State private var loadError: (any Error)?
    let notebookID: Notebook.ID?
    @Binding var selection: Note.ID?

    var body: some View {
        List(store.notes.filter { $0.notebookID == notebookID }, selection: $selection) { note in
            NoteRow(note: note)
        }
        .refreshable { await refreshFromServer() }
    }

    /// Main-actor work: reads and mutates the store. `.refreshable`'s closure is `@Sendable`, so it only awaits this.
    private func refreshFromServer() async {
        do {
            let remote = try await notesAPIClient.notes(since: lastRemoteSync)
            for note in remote.map(\.note) where !store.notes.contains(where: { $0.id == note.id }) {
                store.add(note)
            }
            lastRemoteSync = .now
        } catch is CancellationError {
            // The list went away mid-refresh: nothing to report.
        } catch {
            loadError = error
        }
    }
}

// Packages/FieldNotesKit/Sources/FieldNotesServices/Networking/URLSession+FieldNotes.swift
import Foundation

extension URLSession {
    /// The session NotesAPIClient uses in the app.
    public static let fieldNotesAPI: URLSession = {
        let configuration = URLSessionConfiguration.default
        configuration.waitsForConnectivity = true            // wait for a network instead of failing at once
        configuration.timeoutIntervalForResource = 60        // give up on a request after a minute in total
        configuration.allowsConstrainedNetworkAccess = true  // the note list is small; Low Data Mode is fine
        configuration.httpAdditionalHeaders = ["User-Agent": "FieldNotes/2.0"]
        return URLSession(configuration: configuration)
    }()
}

// Packages/FieldNotesKit/Sources/FieldNotesServices/Networking/AttachmentDownloader.swift
import Foundation
import Synchronization
import FieldNotesModel

/// Owns the one background URLSession of the app. `@unchecked Sendable` because `session` is assigned once
/// in `init` and never changed, and all other mutable state is behind a Mutex.
public final class AttachmentDownloader: NSObject, @unchecked Sendable {
    public static let sessionIdentifier = "com.example.fieldnotes.attachments"

    /// One instance per process, created on first use, including when the system relaunches the app.
    public static let shared = AttachmentDownloader()

    public typealias FinishedHandler = @Sendable (_ attachmentID: UUID, _ file: URL) async -> Void

    private struct State {
        var finishedHandler: FinishedHandler?
        var eventsFinished: [CheckedContinuation<Void, Never>] = []
        var deliveredWithoutWaiter = false     // events finished before anyone started waiting
    }

    private var session: URLSession!
    private let state = Mutex(State())

    private override init() {
        super.init()
        let configuration = URLSessionConfiguration.background(withIdentifier: Self.sessionIdentifier)
        configuration.sessionSendsLaunchEvents = true   // relaunch the app when transfers finish
        configuration.isDiscretionary = true            // let the system pick Wi-Fi and power
        session = URLSession(configuration: configuration, delegate: self, delegateQueue: nil)
    }

    /// The app sets this once at launch: it stores the downloaded file in SwiftData (page 21).
    public func setFinishedHandler(_ handler: @escaping FinishedHandler) {
        state.withLock { $0.finishedHandler = handler }
    }

    public func enqueue(_ attachments: [PhotoAttachment], using client: NotesAPIClient) async throws {
        for attachment in attachments {
            let request = try await client.downloadRequest(for: attachment)
            let task = session.downloadTask(with: request)
            task.taskDescription = attachment.id.uuidString      // survives relaunch; maps the file back
            task.countOfBytesClientExpectsToReceive = 4 * 1024 * 1024
            task.resume()
        }
    }

    /// Suspends until the session has delivered every pending event. Called on background relaunch.
    public func waitForBackgroundEvents() async {
        await withCheckedContinuation { continuation in
            let alreadyDelivered = state.withLock { state in
                if state.deliveredWithoutWaiter {
                    state.deliveredWithoutWaiter = false
                    return true
                }
                state.eventsFinished.append(continuation)
                return false
            }
            if alreadyDelivered { continuation.resume() }
        }
    }
}

extension AttachmentDownloader: URLSessionDownloadDelegate {
    public func urlSession(_ session: URLSession, downloadTask: URLSessionDownloadTask,
                           didFinishDownloadingTo location: URL) {
        guard let id = downloadTask.taskDescription.flatMap(UUID.init(uuidString:)),
              let http = downloadTask.response as? HTTPURLResponse, (200..<300).contains(http.statusCode)
        else { return }
        // `location` is deleted when this method returns: move the file synchronously, before returning.
        let destination = FieldNotesPaths.attachments.appending(path: id.uuidString)
        do {
            try FieldNotesPaths.prepareAttachmentsDirectory()
            try? FileManager.default.removeItem(at: destination)
            try FileManager.default.moveItem(at: location, to: destination)
        } catch {
            return
        }
        if let handler = state.withLock({ $0.finishedHandler }) {
            Task { await handler(id, destination) }
        }
    }

    public func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: (any Error)?) {
        // Failed tasks are retried at the next sync; resume data could be kept here for large files.
    }

    public func urlSessionDidFinishEvents(forBackgroundURLSession session: URLSession) {
        let waiting = state.withLock { state in
            defer { state.eventsFinished.removeAll() }
            state.deliveredWithoutWaiter = state.eventsFinished.isEmpty
            return state.eventsFinished
        }
        waiting.forEach { $0.resume() }
    }
}

// FieldNotes/FieldNotesApp.swift (excerpt: persistence wiring unchanged from Persisting Models with SwiftData)
import SwiftUI
import SwiftData
import FieldNotesServices

@main
struct FieldNotesApp: App {
    private let container: ModelContainer
    @State private var store: NoteStore
    @State private var connectivity = ConnectivityMonitor()

    init() {
        do {
            container = try ModelContainer.fieldNotes()
        } catch {
            fatalError("FieldNotes could not open its store: \(error)")
        }
        _store = State(initialValue: NoteStore(
            syncer: CloudNoteSyncer(),
            persistence: SwiftDataNotePersistence(modelContainer: container)))
        Self.registerDefaultPreferences()
        // Also calls AttachmentDownloader.shared.setFinishedHandler(_:) here (described above).
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(store)
                .environment(connectivity)
                .task { await store.load() }
                .task { await connectivity.run() }
        }
        .modelContainer(container)
        .defaultAppStorage(.fieldNotesShared)
        #if os(iOS) || os(visionOS)
        .backgroundTask(.urlSession(AttachmentDownloader.sessionIdentifier)) {
            await AttachmentDownloader.shared.waitForBackgroundEvents()
        }
        #endif
    }
}

// FieldNotes/iOS/FieldNotesAppDelegate.swift (excerpt)
#if os(iOS) || os(visionOS)
import UIKit
import FieldNotesServices

extension FieldNotesAppDelegate {
    func application(_ application: UIApplication,
                     handleEventsForBackgroundURLSession identifier: String) async {
        guard identifier == AttachmentDownloader.sessionIdentifier else { return }
        await AttachmentDownloader.shared.waitForBackgroundEvents()
    }
}
#endif

// Packages/FieldNotesKit/Sources/FieldNotesServices/Networking/FieldSessionChannel.swift
import Network

public enum FieldSessionChannel {
    /// Connects to the field-session relay, sends the participant's notes as they're captured,
    /// and applies notes from other participants. Returns when the relay closes the connection.
    public static func join(sending outgoing: AsyncStream<RemoteNote>,
                            receiving apply: @escaping @Sendable (RemoteNote) async -> Void) async throws {
        let connection = NetworkConnection(to: .hostPort(host: "live.fieldnotes.example.com", port: 7443)) {
            Coder(RemoteNote.self, using: .json) {
                TLS()
            }
        }

        try await withThrowingDiscardingTaskGroup { group in
            group.addTask {
                for await note in outgoing {
                    try await connection.send(note)
                }
            }
            group.addTask {
                for try await message in connection.messages {
                    await apply(message.content)
                }
            }
        }
    }
}

// FieldNotes/macOS/ClassroomListener.swift
#if os(macOS)
import Network
import FieldNotesServices

func runClassroomListener(store: NoteStore) async throws {
    let listener = try NetworkListener(for: BonjourListenerProvider(name: "FieldNotes Classroom",
                                                                    type: "_fieldnotes._tcp")) {
        Coder(RemoteNote.self, using: .json) {
            TCP()
        }
    }
    try await listener.run { connection in
        for try await message in connection.messages {
            let note = message.content.note
            await MainActor.run { store.add(note) }
        }
    }
}
#endif

// Legacy: NWConnection with callbacks (not used by FieldNotes)
import Foundation
import Network

func sendLegacy(_ data: Data) {
    let connection = NWConnection(host: "live.fieldnotes.example.com", port: 7443, using: .tls)
    connection.stateUpdateHandler = { state in
        if case .failed(let error) = state { print("Connection failed: \(error)") }
    }
    connection.start(queue: .global())
    connection.send(content: data, completion: .contentProcessed { error in
        if let error { print("Send failed: \(error)") }
        connection.cancel()
    })
}