04 · The photo from another row

public protocol ProductFetching: Sendable {
    func fetchProducts() async throws -> [Product]
}

public protocol ImageDownloading: Sendable {
    func imageData(for url: URL) async throws -> Data
}

import ProductCatalog
import UIKit

enum ImageLoaderError: Error {
    case undecodable
}

/// Downloads product images, shrinks them to thumbnails and keeps them in memory.
actor ImageLoader {
    init(downloader: any ImageDownloading, thumbnailSize: CGSize) {
        self.downloader = downloader
        self.thumbnailSize = thumbnailSize
    }

    func image(for url: URL) async throws -> UIImage {
        if let cached = cache[url] {
            return cached
        }
        let data = try await downloader.imageData(for: url)
        let image = try await Self.thumbnail(from: data, size: thumbnailSize)
        cache[url] = image                      // only the actor touches the cache
        return image
    }

    private let downloader: any ImageDownloading
    private let thumbnailSize: CGSize
    private var cache: [URL: UIImage] = [:]

    /// Decodes straight to the size on screen: 180 × 180 px instead of a 1200 × 1200 bitmap.
    /// `@concurrent` keeps this work off the actor, so other callers aren't blocked behind it.
    @concurrent
    private static func thumbnail(from data: Data, size: CGSize) async throws -> UIImage {
        guard let image = UIImage(data: data),
              let thumbnail = await image.byPreparingThumbnail(ofSize: size) else {
            throw ImageLoaderError.undecodable
        }
        return thumbnail
    }
}

import ProductCatalog
import UIKit

final class ProductsViewController: UIViewController {
    private nonisolated enum Section {
        case main
    }

    private enum State {
        case loading
        case loaded
        case failed(String)
    }

    init(productService: any ProductFetching, imageLoader: ImageLoader) {
        self.productService = productService
        self.imageLoader = imageLoader
        super.init(nibName: nil, bundle: nil)
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) is not supported")
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        title = "Products"
        collectionView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(collectionView)
        configureDataSource()
        Task { await loadProducts() }
    }

    override func updateContentUnavailableConfiguration(using state: UIContentUnavailableConfigurationState) {
        switch self.state {
        case .loading:
            contentUnavailableConfiguration = UIContentUnavailableConfiguration.loading()
        case .failed(let message):
            var configuration = UIContentUnavailableConfiguration.empty()
            configuration.image = UIImage(systemName: "wifi.exclamationmark")
            configuration.text = "Couldn't load products"
            configuration.secondaryText = message
            configuration.button = .borderedProminent()
            configuration.button.title = "Try again"
            configuration.buttonProperties.primaryAction = UIAction { [weak self] _ in
                Task { await self?.loadProducts() }
            }
            contentUnavailableConfiguration = configuration
        case .loaded where products.isEmpty:
            var configuration = UIContentUnavailableConfiguration.empty()
            configuration.text = "No products yet"
            contentUnavailableConfiguration = configuration
        case .loaded:
            contentUnavailableConfiguration = nil
        }
    }

    private let productService: any ProductFetching
    private let imageLoader: ImageLoader
    private var products: [Product.ID: Product] = [:]
    private var dataSource: UICollectionViewDiffableDataSource<Section, Product.ID>!
    private var state: State = .loading {
        didSet { setNeedsUpdateContentUnavailableConfiguration() }
    }
    private lazy var collectionView = UICollectionView(
        frame: view.bounds,
        collectionViewLayout: UICollectionViewCompositionalLayout.list(using: .init(appearance: .plain))
    )

    private func configureDataSource() {
        let registration = UICollectionView.CellRegistration<ProductCell, Product.ID> { [weak self] cell, _, id in
            guard let self, let product = products[id] else { return }
            var content = UIListContentConfiguration.subtitleCell()
            content.text = product.name
            content.secondaryText = product.price.formatted(.currency(code: "EUR"))
            content.image = UIImage(systemName: "photo")
            content.imageProperties.maximumSize = CGSize(width: 60, height: 60)
            content.imageProperties.reservedLayoutSize = CGSize(width: 60, height: 60)
            content.imageProperties.cornerRadius = 8
            cell.contentConfiguration = content

            let placeholder = content
            cell.imageTask = Task { [imageLoader] in
                guard let image = try? await imageLoader.image(for: product.imageURL),
                      !Task.isCancelled else { return }   // the cell was reused while we waited
                var loaded = placeholder
                loaded.image = image
                cell.contentConfiguration = loaded
            }
        }
        dataSource = UICollectionViewDiffableDataSource(collectionView: collectionView) { collectionView, indexPath, id in
            collectionView.dequeueConfiguredReusableCell(using: registration, for: indexPath, item: id)
        }
    }

    private func loadProducts() async {
        state = .loading
        do {
            let products = try await productService.fetchProducts()
            self.products = Dictionary(uniqueKeysWithValues: products.map { ($0.id, $0) })
            var snapshot = NSDiffableDataSourceSnapshot<Section, Product.ID>()
            snapshot.appendSections([.main])
            snapshot.appendItems(products.map(\.id))
            await dataSource.apply(snapshot, animatingDifferences: false)
            state = .loaded
        } catch {
            state = .failed(error.localizedDescription)
        }
    }
}

/// A list cell that owns its image load, so reuse cancels it.
final class ProductCell: UICollectionViewListCell {
    var imageTask: Task<Void, Never>? {
        willSet { imageTask?.cancel() }
    }

    override func prepareForReuse() {
        super.prepareForReuse()
        imageTask = nil
    }
}

let imageLoader = ImageLoader(downloader: ImageService(),
                              thumbnailSize: CGSize(width: 180, height: 180))   // 60 pt at 3x
let products = ProductsViewController(productService: ProductService(), imageLoader: imageLoader)
window.rootViewController = UINavigationController(rootViewController: products)

func image(for url: URL) async throws -> UIImage {
    if let cached = cache[url] {
        return cached
    }
    if let running = inFlight[url] {
        return try await running.value      // join the download that's already running
    }
    let download = Task { [downloader, thumbnailSize] in
        let data = try await downloader.imageData(for: url)
        return try await Self.thumbnail(from: data, size: thumbnailSize)
    }
    inFlight[url] = download                // registered before the first await
    defer { inFlight[url] = nil }
    let image = try await download.value
    cache[url] = image
    return image
}

private var inFlight: [URL: Task<UIImage, any Error>] = [:]

import ProductCatalog
import UIKit

enum ImageLoaderError: Error {
    case undecodable
}

/// Downloads product images, shrinks them to thumbnails and keeps the most recently used
/// ones in memory, up to `costLimit` bytes of decoded pixels.
actor ImageLoader {
    init(downloader: any ImageDownloading, thumbnailSize: CGSize, costLimit: Int) {
        self.downloader = downloader
        self.thumbnailSize = thumbnailSize
        self.costLimit = costLimit
    }

    /// Bytes of decoded pixels in the cache right now.
    private(set) var totalCost = 0

    func image(for url: URL) async throws -> UIImage {
        if let cached = cachedImage(for: url) {
            return cached
        }
        if let running = inFlight[url] {
            return try await running.value      // join the download that's already running
        }
        let download = Task { [downloader, thumbnailSize] in
            let data = try await downloader.imageData(for: url)
            return try await Self.thumbnail(from: data, size: thumbnailSize)
        }
        inFlight[url] = download                // registered before the first await
        defer { inFlight[url] = nil }
        let image = try await download.value
        insert(image, for: url)
        return image
    }

    private struct Entry {
        let image: UIImage
        let cost: Int
    }

    private let downloader: any ImageDownloading
    private let thumbnailSize: CGSize
    private let costLimit: Int
    private var cache: [URL: Entry] = [:]
    private var recency: [URL] = []             // least recently used first
    private var inFlight: [URL: Task<UIImage, any Error>] = [:]

    private func cachedImage(for url: URL) -> UIImage? {
        guard let entry = cache[url] else { return nil }
        recency.removeAll { $0 == url }         // O(n): fine for a few hundred thumbnails
        recency.append(url)
        return entry.image
    }

    private func insert(_ image: UIImage, for url: URL) {
        let cost = Self.cost(of: image)
        guard cost <= costLimit else { return }  // bigger than the whole budget: don't cache it
        cache[url] = Entry(image: image, cost: cost)
        recency.append(url)
        totalCost += cost
        while totalCost > costLimit, let oldest = recency.first {
            recency.removeFirst()
            totalCost -= cache.removeValue(forKey: oldest)?.cost ?? 0
        }
    }

    /// What the image costs in memory once decoded: its bitmap, not its file size.
    private static func cost(of image: UIImage) -> Int {
        guard let cgImage = image.cgImage else { return 0 }
        return cgImage.bytesPerRow * cgImage.height
    }

    // thumbnail(from:size:): unchanged, @concurrent.
}

import Foundation
import ProductCatalog
import Synchronization
import Testing
import UIKit
@testable import ProductImages

/// Counts downloads per URL. Answers after `delay`, and fails the first `failures` requests.
nonisolated final class FakeDownloader: ImageDownloading {
    let delay: Duration
    let failuresLeft: Mutex<Int>
    let requests = Mutex<[URL: Int]>([:])

    init(delay: Duration = .zero, failures: Int = 0) {
        self.delay = delay
        self.failuresLeft = Mutex(failures)
    }

    func imageData(for url: URL) async throws -> Data {
        requests.withLock { $0[url, default: 0] += 1 }
        try await Task.sleep(for: delay)
        let shouldFail = failuresLeft.withLock { left in
            defer { left = max(0, left - 1) }
            return left > 0
        }
        if shouldFail { throw URLError(.timedOut) }
        return Self.png
    }

    func downloads(of url: URL) -> Int {
        requests.withLock { $0[url, default: 0] }
    }

    static let png = UIGraphicsImageRenderer(size: CGSize(width: 300, height: 300)).pngData { context in
        UIColor.orange.setFill()
        context.fill(CGRect(x: 0, y: 0, width: 300, height: 300))
    }
}

struct ImageLoaderTests {
    let a = URL(string: "https://img.example.com/a.png")!
    let b = URL(string: "https://img.example.com/b.png")!
    let c = URL(string: "https://img.example.com/c.png")!
    let thumbnail = CGSize(width: 60, height: 60)

    @Test func concurrentRequestsForOneURLShareOneDownload() async throws {
        let downloader = FakeDownloader(delay: .milliseconds(100))
        let loader = ImageLoader(downloader: downloader, thumbnailSize: thumbnail, costLimit: .max)
        async let first = loader.image(for: a)
        async let second = loader.image(for: a)
        async let third = loader.image(for: a)
        _ = try await (first, second, third)
        #expect(downloader.downloads(of: a) == 1)
    }

    @Test func aCachedImageIsNotDownloadedAgain() async throws {
        let downloader = FakeDownloader()
        let loader = ImageLoader(downloader: downloader, thumbnailSize: thumbnail, costLimit: .max)
        _ = try await loader.image(for: a)
        _ = try await loader.image(for: a)
        #expect(downloader.downloads(of: a) == 1)
    }

    @Test func aFailedDownloadIsNotCachedSoTheNextRequestRetries() async throws {
        let downloader = FakeDownloader(failures: 1)
        let loader = ImageLoader(downloader: downloader, thumbnailSize: thumbnail, costLimit: .max)
        await #expect(throws: URLError.self) { try await loader.image(for: a) }
        _ = try await loader.image(for: a)
        #expect(downloader.downloads(of: a) == 2)
    }

    @Test func aCancelledCallerDoesNotCancelTheSharedDownload() async throws {
        let downloader = FakeDownloader(delay: .milliseconds(200))
        let loader = ImageLoader(downloader: downloader, thumbnailSize: thumbnail, costLimit: .max)
        let leaving = Task { try await loader.image(for: a) }       // a cell scrolled away
        let staying = Task { try await loader.image(for: a) }       // another cell, same photo
        leaving.cancel()
        _ = try await staying.value
        #expect(downloader.downloads(of: a) == 1)
    }

    @Test func theLeastRecentlyUsedImageIsEvictedOverTheLimit() async throws {
        let probe = ImageLoader(downloader: FakeDownloader(), thumbnailSize: thumbnail, costLimit: .max)
        _ = try await probe.image(for: a)
        let oneImage = await probe.totalCost                         // what one thumbnail costs

        let downloader = FakeDownloader()
        let loader = ImageLoader(downloader: downloader, thumbnailSize: thumbnail,
                                 costLimit: oneImage * 2)              // room for two
        _ = try await loader.image(for: a)
        _ = try await loader.image(for: b)
        _ = try await loader.image(for: a)                            // a is now the most recent
        _ = try await loader.image(for: c)                            // evicts b, not a
        #expect(await loader.totalCost <= oneImage * 2)

        _ = try await loader.image(for: a)
        _ = try await loader.image(for: b)
        #expect(downloader.downloads(of: a) == 1)
        #expect(downloader.downloads(of: b) == 2)
    }
}