Kingfisher Documentation

File: README.md Copy Chapter

Kingfisher is a powerful, pure-Swift library for downloading and caching images from the web. It provides you a chance to use a pure-Swift way to work with remote images in your next app.

Features Copy Chapter

• Asynchronous image downloading and caching.
• Loading image from either URLSession-based networking or local provided data.
• Useful image processors and filters provided.
• Multiple-layer hybrid cache for both memory and disk.
• Fine control on cache behavior. Customizable expiration date and size limit.
• Opt-in async cache probing in KingfisherManager to avoid blocking the caller thread on disk cache checks.
• Cancelable downloading and auto-reusing previous downloaded content to improve performance.
• Independent components. Use the downloader, caching system, and image processors separately as you need.
• Prefetching images and showing them from the cache to boost your app.
• Extensions for UIImageView, NSImageView, NSButton, UIButton, NSTextAttachment, WKInterfaceImage, TVMonogramView and CPListItem to directly set an image from a URL.
• Built-in transition animation when setting images.
• Customizable placeholder and indicator while loading images.
• Extensible image processing and image format easily.
• Low Data Mode support.
• SwiftUI support.
• Swift 6 & Swift Concurrency (strict mode) prepared.
• Load & cache for Live Photo.

Kingfisher 101 Copy Section

The simplest use-case is setting an image to an image view with the UIImageView extension:

import Kingfisher

let url = URL(string: "https://example.com/image.png")
imageView.kf.setImage(with: url)

Kingfisher will download the image from url, send it to both memory cache and disk cache, and display it in imageView.
When you set it with the same URL later, the image will be retrieved from the cache and shown immediately.

It also works if you use SwiftUI:

var body: some View {
    KFImage(URL(string: "https://example.com/image.png")!)
}

A More Advanced Example Copy Section

With the powerful options, you can do hard tasks with Kingfisher in a simple way. For example, the code below:

1. Downloads a high-resolution image.
2. Downsamples it to match the image view size.
3. Makes it round cornered with a given radius.
4. Shows a system indicator and a placeholder image while downloading.
5. When prepared, it animates the small thumbnail image with a "fade in" effect.
6. The original large image is also cached to disk for later use, to get rid of downloading it again in a detail view.
7. A console log is printed when the task finishes, either for success or failure.

let url = URL(string: "https://example.com/high_resolution_image.png")
let processor = DownsamplingImageProcessor(size: imageView.bounds.size)
             |> RoundCornerImageProcessor(cornerRadius: 20)
imageView.kf.indicatorType = .activity
imageView.kf.setImage(
    with: url,
    placeholder: UIImage(named: "placeholderImage"),
    options: [
        .processor(processor),
        .scaleFactor(UIScreen.main.scale),
        .transition(.fade(1)),
        .cacheOriginalImage
    ])
{
    result in
    switch result {
    case .success(let value):
        print("Task done for: \(value.source.url?.absoluteString ?? "")")
    case .failure(let error):
        print("Job failed: \(error.localizedDescription)")
    }
}

It is a common situation I can meet in my daily work. Think about how many lines you need to write without
Kingfisher!

Method Chaining Copy Section

If you are not a fan of the kf extension, you can also prefer to use the KF builder and chained the method
invocations. The code below is doing the same thing:

// Use `kf` extension
imageView.kf.setImage(
    with: url,
    placeholder: placeholderImage,
    options: [
        .processor(processor),
        .loadDiskFileSynchronously,
        .cacheOriginalImage,
        .transition(.fade(0.25)),
        .lowDataMode(.network(lowResolutionURL))
    ],
    progressBlock: { receivedSize, totalSize in
        // Progress updated
    },
    completionHandler: { result in
        // Done
    }
)

// Use `KF` builder
KF.url(url)
  .placeholder(placeholderImage)
  .setProcessor(processor)
  .loadDiskFileSynchronously()
  .cacheMemoryOnly()
  .fade(duration: 0.25)
  .lowDataModeSource(.network(lowResolutionURL))
  .onProgress { receivedSize, totalSize in  }
  .onSuccess { result in  }
  .onFailure { error in }
  .set(to: imageView)

And even better, if later you want to switch to SwiftUI, just change the KF above to KFImage, and you've done:

struct ContentView: View {
    var body: some View {
        KFImage.url(url)
          .placeholder(placeholderImage)
          .setProcessor(processor)
          .loadDiskFileSynchronously()
          .cacheMemoryOnly()
          .fade(duration: 0.25)
          .lowDataModeSource(.network(lowResolutionURL))
          .onProgress { receivedSize, totalSize in  }
          .onSuccess { result in  }
          .onFailure { error in }
    }
}

Requirements Copy Chapter

Kingfisher 8.0 Copy Section

• (UIKit/AppKit) iOS 13.0+ / macOS 10.15+ / tvOS 13.0+ / watchOS 6.0+ / visionOS 1.0+
• (SwiftUI) iOS 14.0+ / macOS 11.0+ / tvOS 14.0+ / watchOS 7.0+ / visionOS 1.0+
• Swift 5.9+

Kingfisher 7.0 Copy Section

• (UIKit/AppKit) iOS 12.0+ / macOS 10.14+ / tvOS 12.0+ / watchOS 5.0+ / visionOS 1.0+
• (SwiftUI) iOS 14.0+ / macOS 11.0+ / tvOS 14.0+ / watchOS 7.0+ / visionOS 1.0+
• Swift 5.0+

Installation Copy Section

Refer to one of the following tutorials to install and use the framework:

• UIKit Tutorial
• SwiftUI Tutorial

Alternatively, you can follow either of the methods below.

Swift Package Manager

• File > Swift Packages > Add Package Dependency
• Add https://github.com/onevcat/Kingfisher.git
• Select "Up to Next Major" with "8.0.0"

CocoaPods

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '13.0'
use_frameworks!

target 'MyApp' do
  pod 'Kingfisher', '~> 8.0'
end

Pre-built Framework

1. Open the release page, download the latest version of Kingfisher from the assets section.
2. Drag the Kingfisher.xcframework into your project and add it to the target (usually the app target).
3. Select your target, in the "General" Tab, find the "Frameworks, Libraries, and Embedded Content" section, set the Embed Without Signing to Kingfisher.

Documentation Copy Chapter

Check the documentation and tutorials:

• Documentation Home
• Getting Started
  • UIKit Tutorial
  • SwiftUI Tutorial
• Common Tasks - General
  • Common Tasks - Cache
  • Common Tasks - Downloader
  • Common tasks - Processor

Migrating Copy Section

• Kingfisher 8.0 Migration
• Kingfisher 7.0 Migration

If you are using an even earlier version, see the guides below to know the steps for migrating.

Other Copy Chapter

Future of Kingfisher Copy Section

I want to keep Kingfisher lightweight. This framework focuses on providing a simple solution for downloading and caching images. This doesn’t mean the framework can’t be improved. Kingfisher is far from perfect, so necessary and useful updates will be made to make it better.

Developments and Tests Copy Section

Any contributing and pull requests are warmly welcome. However, before you plan to implement some features or try to fix an uncertain issue, it is recommended to open a discussion first. It would be appreciated if your pull requests could build with all tests green. :)

About the logo Copy Section

The logo of Kingfisher is inspired by Tangram (七巧板), a dissection puzzle consisting of seven flat shapes from China. I believe she's a kingfisher bird instead of a swift, but someone insists that she is a pigeon. I guess I should give her a name. Hi, guys, do you have any suggestions?

Contact Copy Section

Follow and contact me on Twitter or Sina Weibo. If you find an issue, open a ticket. Pull requests are warmly welcome as well.

Backers & Sponsors Copy Chapter

Open-source projects cannot live long without your help. If you find Kingfisher to be useful, please consider supporting this
project by becoming a sponsor. Your user icon or company logo shows up on my blog with a link to your home page.

Become a sponsor through GitHub Sponsors. :heart:

Special thanks to:

License Copy Section

Kingfisher is released under the MIT license. See LICENSE for details.

File: docs/architecture.md Copy Chapter

Kingfisher Architecture Documentation

High-Level System Organization Copy Chapter

Kingfisher is a sophisticated image loading and caching library for Apple platforms, designed with a modular architecture that promotes separation of concerns and extensibility. At its core, the library employs a coordinator pattern where KingfisherManager serves as the central orchestrator, managing the flow between network operations, caching layers, and image processing pipelines. The architecture leverages protocol-oriented design principles, with all functionality exposed through a .kf namespace wrapper that provides a clean, chainable API surface.

The system is built on three fundamental pillars: downloading, caching, and processing. The ImageDownloader handles all network operations with support for authentication, retries, and progressive loading. The ImageCache implements a dual-layer caching strategy combining memory and disk storage for optimal performance. The ImageProcessor protocol enables a flexible transformation pipeline where multiple processors can be chained together. These components work in concert through a sophisticated options system (KingfisherOptionsInfo) that allows fine-grained control over every aspect of the image loading process.

Cross-platform compatibility is achieved through extensive use of conditional compilation and type aliases, allowing the same codebase to support iOS, macOS, tvOS, watchOS, and visionOS. The library provides both UIKit/AppKit extensions and dedicated SwiftUI components (KFImage, KFAnimatedImage), ensuring seamless integration regardless of the UI framework being used.

Component Map Copy Chapter

Core Components Copy Section

Storage Layer Copy Section

Networking Layer Copy Section

UI Integration Copy Section

Key Files Copy Chapter

KingfisherManager.swift (Lines 107-420) Copy Section

The heart of the library, containing:

• shared singleton instance (line 113)
• retrieveImage() main entry point (lines 196-210, 233-248)
• Cache lookup logic (lines 400-403)
• Download coordination (lines 415-418)
• Retry and alternative source handling (lines 306-385)

ImageDownloader.swift (Lines 35-150) Copy Section

Network layer implementation:

• ImageLoadingResult struct for download results (lines 36-58)
• DownloadTask class for cancellable downloads (lines 65-102)
• URLSession management and request handling

ImageCache.swift (Lines 52-200) Copy Section

Caching infrastructure:

• CacheType enum defining cache levels (lines 52-72)
• Memory and disk cache coordination
• Cache key generation and expiration logic

KF.swift (Lines 50-100) Copy Section

Builder pattern implementation:

• Static factory methods for creating builders (lines 56-99)
• Fluent API entry points for different source types

ImageProcessor.swift (Lines 37-100) Copy Section

Processing pipeline:

• ImageProcessItem enum for input types (lines 37-46)
• ImageProcessor protocol definition (lines 49-76)
• Processor chaining via append() (lines 85-95)

KingfisherOptionsInfo.swift (Lines 43-250) Copy Section

Configuration system:

• Option items enumeration with associated values
• Cache, downloader, and processor configuration
• Transition and placeholder settings

Data Flow Copy Chapter

1. Image Request Initiation Copy Section

UIImageView.kf.setImage(with: url)
    │
    └─> ImageView+Kingfisher.swift (line 77-87)
        │
        └─> KingfisherManager.retrieveImage()
            Sources/General/KingfisherManager.swift (line 196)

2. Cache Lookup Copy Section

KingfisherManager.retrieveImage()
    │
    └─> retrieveImageFromCache() (line 400)
        │
        ├─> ImageCache.retrieveImage()
        │   Sources/Cache/ImageCache.swift
        │   │
        │   ├─> MemoryStorage.value(forKey:)
        │   │   Sources/Cache/MemoryStorage.swift
        │   │
        │   └─> DiskStorage.value(forKey:)
        │       Sources/Cache/DiskStorage.swift
        │
        └─> [Cache Hit] → completionHandler(.success)
            [Cache Miss] → Continue to download

3. Network Download Copy Section

KingfisherManager.loadAndCacheImage() (line 415)
    │
    └─> ImageDownloader.downloadImage()
        Sources/Networking/ImageDownloader.swift
        │
        ├─> SessionDelegate.downloadTask()
        │   Sources/Networking/SessionDelegate.swift
        │
        └─> URLSession.dataTask()
            │
            └─> CompletionHandler with ImageLoadingResult

4. Image Processing Copy Section

Downloaded Data
    │
    └─> ImageProcessor.process() (line 434)
        Sources/Image/ImageProcessor.swift
        │
        ├─> DefaultImageProcessor (if none specified)
        │
        └─> Custom processors chain
            │
            └─> Processed KFCrossPlatformImage

5. Cache Storage Copy Section

Processed Image
    │
    └─> KingfisherManager.cacheImage() (line 459)
        │
        ├─> ImageCache.store() (line 482)
        │   │
        │   ├─> MemoryStorage.store()
        │   │   In-memory cache with cost calculation
        │   │
        │   └─> DiskStorage.store()
        │       File system with expiration
        │
        └─> completionHandler(.success(RetrieveImageResult))
            │
            └─> UI Update on main queue

6. Error Handling and Retry Copy Section

Download/Processing Error
    │
    └─> RetryStrategy.retry() (line 362)
        Sources/Networking/RetryStrategy.swift
        │
        ├─> [Retry] → startNewRetrieveTask() (line 306)
        │
        └─> [No Retry] → Check alternative sources (line 334)
            │
            ├─> [Alternative exists] → Start new task
            │
            └─> [No alternatives] → completionHandler(.failure)

This architecture enables Kingfisher to efficiently handle image loading with features like progressive downloading, multiple cache layers, flexible processing pipelines, and robust error handling, all while maintaining a clean and intuitive API surface for developers.

File: docs/build-system.md Copy Chapter

Kingfisher Build System Documentation

Overview Copy Chapter

Kingfisher uses a dual build system approach supporting both Swift Package Manager and Fastlane/CocoaPods for maximum flexibility and distribution options.

Primary Build Tools Copy Section

• Swift Package Manager (Package.swift) - Modern dependency management and building
• Fastlane (fastlane/Fastfile) - Automated testing, building, and release workflows
• CocoaPods (Kingfisher.podspec) - Legacy distribution and integration
• GitHub Actions (.github/workflows/) - Continuous integration and testing

Key Configuration Files Copy Section

.
├── Package.swift                    # Swift Package Manager configuration
├── Kingfisher.podspec              # CocoaPods specification
├── Gemfile                         # Ruby dependencies for Fastlane/CocoaPods
├── fastlane/
│   ├── Fastfile                    # Fastlane automation workflows
│   └── actions/                    # Custom Fastlane actions
└── .github/workflows/
    ├── build.yaml                  # CI build workflow
    └── test.yaml                   # CI test workflow

Build Workflows Copy Chapter

Building with Swift Package Manager Copy Section

# Build for default platform
swift build

# Build with specific Swift version
swift build -Xswiftc -swift-version -Xswiftc 5

# Build for release
swift build -c release

# Build and run tests
swift test

# Generate Xcode project (if needed)
swift package generate-xcodeproj

Building with Fastlane Copy Section

First, install dependencies:

# Install Ruby dependencies
bundle install

Common build commands:

# Run all platform tests (iOS, macOS, tvOS, watchOS)
bundle exec fastlane tests

# Build for CI with specific destination
DESTINATION="platform=iOS Simulator,name=iPhone 15,OS=17.5" bundle exec fastlane build_ci

# Test for CI with specific destination  
DESTINATION="platform=macOS" bundle exec fastlane test_ci

# Build specific platform
bundle exec fastlane build destination:"platform=iOS Simulator,name=iPhone 15"

# Lint both CocoaPods and SPM
bundle exec fastlane lint

Release Process Copy Section

The release workflow automates versioning, tagging, and distribution:

# Full release (tests, lint, version bump, GitHub release, CocoaPods push)
bundle exec fastlane release version:X.X.X

# Skip tests during release
bundle exec fastlane release version:X.X.X skip_tests:true

# Create XCFramework for distribution
bundle exec fastlane xcframework version:X.X.X

Release steps performed:

1. Ensures clean git state and correct branch
2. Runs all tests (unless skipped)
3. Lints CocoaPods spec and SPM package
4. Updates version in all configuration files
5. Extracts and updates changelog
6. Creates signed git tag
7. Builds XCFramework for all platforms
8. Creates GitHub release with assets
9. Pushes to CocoaPods trunk

Platform-specific Setup Copy Chapter

Supported Platforms Copy Section

From Package.swift and Kingfisher.podspec:

• iOS: 13.0+
• macOS: 10.15+
• tvOS: 13.0+
• watchOS: 6.0+
• visionOS: 1.0+

CI Test Matrix Copy Section

From .github/workflows/test.yaml:

• Destinations: macOS, iOS Simulator, tvOS Simulator, watchOS Simulator
• Xcode Versions: 15.4, 16.2

Platform Build Commands Copy Section

# macOS
bundle exec fastlane test destination:"platform=macOS"

# iOS Simulator
bundle exec fastlane test destination:"platform=iOS Simulator,name=iPhone 15,OS=17.5"

# tvOS Simulator  
bundle exec fastlane test destination:"platform=tvOS Simulator,name=Apple TV,OS=17.5"

# watchOS Simulator (build only, no test)
bundle exec fastlane build destination:"platform=watchOS Simulator,name=Apple Watch Series 9 (41mm),OS=10.5"

Reference Copy Chapter

Build Targets Copy Section

From Package.swift:

• Library: Kingfisher (single library product)
• Target: Kingfisher (sources in Sources/ directory)

Fastlane Lanes Copy Section

Available lanes in fastlane/Fastfile:

Environment Variables Copy Section

Custom Fastlane Actions Copy Section

Located in fastlane/actions/:

• extract_current_change_log.rb - Extract changelog for version
• git_commit_all.rb - Commit all changes
• sync_build_number_to_git.rb - Sync build number with git
• update_change_log.rb - Update changelog file

Troubleshooting Copy Section

Common Issues

1. Bundle install fails

   bash Copy

   # Update bundler
   gem install bundler
   
   # Install with specific bundler version
   bundle _2.x.x_ install

2. Xcode version mismatch

   bash Copy

   # Set Xcode version explicitly
   XCODE_VERSION=16.2 bundle exec fastlane tests
   
   # Or use xcode-select
   sudo xcode-select -s /Applications/Xcode_16.2.app

3. Simulator not found

   bash Copy

   # List available simulators
   xcrun simctl list devices
   
   # Update destination string accordingly

4. CocoaPods push fails

   bash Copy

   # Verify pod spec locally first
   pod lib lint Kingfisher.podspec
   
   # Register session if needed
   pod trunk register [email protected]

5. Swift version issues

   bash Copy

   # Override Swift version in build
   bundle exec fastlane build xcargs:"SWIFT_VERSION=5.9"

Build Settings Copy Section

Key build settings used:

• BUILD_LIBRARY_FOR_DISTRIBUTION: YES (for XCFramework)
• SKIP_INSTALL: NO (for archiving)
• SWIFT_VERSION: 5.0 (default, can be overridden)

Distribution Artifacts Copy Section

Release builds generate:

• Kingfisher-{version}.xcframework.zip - All platforms XCFramework
• Kingfisher-iOS-{version}.xcframework.zip - iOS-only XCFramework

Both are code-signed with Apple Distribution certificate and uploaded to GitHub releases.

File: docs/deployment.md Copy Chapter

Deployment Guide

This document provides comprehensive guidance for deploying Kingfisher across different platforms and distribution channels.

Overview Copy Chapter

Kingfisher supports multiple deployment strategies:

• CocoaPods: Traditional CocoaPods spec deployment
• Swift Package Manager: Native Swift package distribution
• XCFramework: Pre-built universal frameworks
• GitHub Releases: Automated release management

The deployment process is fully automated using Fastlane with comprehensive platform coverage across iOS, macOS, tvOS, watchOS, and visionOS.

Package Types Copy Chapter

CocoaPods Distribution Copy Section

Configuration File: /Users/onevcat/Sync/github/Kingfisher/Kingfisher.podspec

Build Targets:

• iOS 13.0+
• macOS 10.15+
• tvOS 13.0+
• watchOS 6.0+
• visionOS 1.0+

Key Features:

• Module stability enabled (BUILD_LIBRARY_FOR_DISTRIBUTION)
• Privacy manifest included (PrivacyInfo.xcprivacy)
• Weak framework dependencies (SwiftUI, Combine)
• Required frameworks (CFNetwork, Accelerate)

Swift Package Manager Copy Section

Configuration File: /Users/onevcat/Sync/github/Kingfisher/Package.swift

Build Targets:

• Single library target: Kingfisher
• Source path: Sources/
• Minimum Swift tools version: 5.1

Platform Support:

• iOS 13.0+
• macOS 10.15+
• tvOS 13.0+
• watchOS 6.0+

XCFramework Distribution Copy Section

Output Locations:

build/
├── Kingfisher-{version}.xcframework.zip          # All platforms
├── Kingfisher-iOS-{version}.xcframework.zip      # iOS only
├── Kingfisher-{version}/
│   └── Kingfisher.xcframework/
│       ├── ios-arm64/
│       ├── ios-arm64_x86_64-simulator/
│       ├── macos-arm64_x86_64/
│       ├── tvos-arm64/
│       ├── tvos-arm64_x86_64-simulator/
│       ├── watchos-arm64_arm64_32_armv7k/
│       ├── watchos-arm64_i386_x86_64-simulator/
│       ├── xros-arm64/
│       └── xros-arm64_x86_64-simulator/

Platform-Specific Archives:

build/
├── Kingfisher-iphoneos.xcarchive/
├── Kingfisher-iphonesimulator.xcarchive/
├── Kingfisher-macosx.xcarchive/
├── Kingfisher-appletvos.xcarchive/
├── Kingfisher-appletvsimulator.xcarchive/
├── Kingfisher-watchos.xcarchive/
├── Kingfisher-watchsimulator.xcarchive/
├── Kingfisher-xros.xcarchive/
└── Kingfisher-xrsimulator.xcarchive/

Platform-Specific Deployment Copy Chapter

iOS Deployment Copy Section

• Device: iphoneos SDK
• Simulator: iphonesimulator SDK
• Architectures: arm64, x86_64 (simulator)
• Framework Path: build/Kingfisher-iOS-{version}.xcframework.zip

macOS Deployment Copy Section

• SDK: macosx
• Architectures: arm64, x86_64 (universal)
• Framework Structure: Traditional bundle format with versioning

tvOS Deployment Copy Section

• Device: appletvos SDK
• Simulator: appletvsimulator SDK
• Architectures: arm64, x86_64 (simulator)

watchOS Deployment Copy Section

• Device: watchos SDK
• Simulator: watchsimulator SDK
• Architectures: arm64, arm64_32, armv7k (device), i386, x86_64, arm64 (simulator)

visionOS Deployment Copy Section

• Device: xros SDK
• Simulator: xrsimulator SDK
• Architectures: arm64, x86_64 (simulator)

Deployment Commands Copy Chapter

Complete Release Process Copy Section

# Full release workflow
bundle exec fastlane release version:X.X.X

# Skip tests during release (not recommended)
bundle exec fastlane release version:X.X.X skip_tests:true

Individual Components Copy Section

# Create XCFramework only
bundle exec fastlane xcframework version:X.X.X

# Run linting
bundle exec fastlane lint

# Build for specific platform
bundle exec fastlane build_ci

CocoaPods Deployment Copy Section

# Lint podspec
pod lib lint Kingfisher.podspec

# Push to CocoaPods trunk (automated in release)
pod trunk push Kingfisher.podspec

Swift Package Manager Copy Section

# Build with SPM
swift build

# Test with SPM
swift test

# Validate package
swift package resolve

Continuous Integration Copy Chapter

GitHub Actions Workflows Copy Section

Build Workflow: .github/workflows/build.yaml

• Builds across multiple Xcode versions (15.2, 15.3, 16.0, 16.1)
• Tests all platforms in matrix configuration
• Uses self-hosted runners

Test Workflow: .github/workflows/test.yaml

• Runs tests on Xcode 15.4 and 16.2
• Covers all platform destinations
• Concurrent execution with cancellation

Matrix Configuration:

destination: [
  'macOS',
  'iOS Simulator,name=iPhone 15,OS=17.5',
  'tvOS Simulator,name=Apple TV,OS=17.5',
  'watchOS Simulator,name=Apple Watch Series 9 (41mm),OS=10.5'
]

Release Management Copy Chapter

Automated Release Process Copy Section

The release process handles:

1. Pre-release Validation:

   • Git branch verification
   • Clean git status check
   • Comprehensive testing across platforms
   • Podspec and SPM linting

2. Version Management:

   • Build number synchronization
   • Version number increment
   • Podspec version update
   • Changelog extraction

3. Build Artifacts:

   • XCFramework creation for all platforms
   • Code signing with Apple Distribution certificate
   • ZIP archive creation

4. Distribution:

   • Git tag creation with signing
   • GitHub release creation
   • Asset upload (both full and iOS-only XCFrameworks)
   • CocoaPods trunk push

Changelog Management Copy Section

Configuration: /Users/onevcat/Sync/github/Kingfisher/pre-change.yml

Structure:

version: X.X.X
name: Release Name
fix:
  - Bug fix descriptions with issue links
add:
  - New feature descriptions

Version Tagging Copy Section

• Format: Semantic versioning (X.X.X)
• Signing: GPG signed tags
• Automation: Integrated with release workflow

Reference Copy Chapter

Deployment Scripts Copy Section

Build Output Locations Copy Section

Environment Variables Copy Section

Code Signing Copy Section

• Certificate: Apple Distribution: Wei Wang (A4YJ9MRZ66)
• Timestamp: Enabled for all XCFramework builds
• Verification: Automated signature verification

Server Configurations Copy Section

GitHub Actions:

• Runner Type: Self-hosted
• Concurrency: Group-based with cancellation
• Shell: bash -leo pipefail {0}

Ruby Environment:

• Fastlane: Latest version
• CocoaPods: Latest version
• xcodes: For Xcode version management

This deployment system ensures reliable, automated distribution across all supported Apple platforms with comprehensive testing and validation at each step.

File: docs/development.md Copy Chapter

Development Guide

Overview Copy Chapter

Kingfisher follows a modular architecture designed for maintainability, testability, and cross-platform compatibility. The development environment emphasizes protocol-oriented programming, namespace safety, and comprehensive test coverage. The codebase is organized into distinct functional modules with clear separation of concerns, following Swift's modern concurrency patterns and maintaining compatibility across iOS, macOS, tvOS, watchOS, and visionOS platforms.

The codebase implements several sophisticated design patterns including the namespace wrapper pattern for API safety, builder patterns for fluent configuration, and options patterns for flexible customization. All components are designed to be thread-safe with explicit concurrency annotations where needed. Development follows strict code style guidelines with comprehensive documentation, ensuring consistency across the large codebase.

Testing is integral to the development process, with extensive unit tests covering all major components, network mocking for reliable testing, and cross-platform validation. The build system uses Fastlane for automation, supporting multiple deployment targets and maintaining high quality standards through automated linting and testing workflows.

Code Style Conventions Copy Chapter

File Headers and Documentation Copy Section

All source files must include the standard license header:

//
//  FileName.swift
//  Kingfisher
//
//  Created by [Author] on [Date].
//
//  Copyright (c) 2019 Wei Wang <[email protected]>
//
//  Permission is hereby granted, free of charge, to any person obtaining a copy
//  of this software and associated documentation files (the "Software")...

Naming Conventions Copy Section

• Files: Use PascalCase with descriptive names (ImageProcessor.swift, KingfisherManager.swift)
• Types: PascalCase for classes, structs, protocols, and enums
• Methods/Properties: camelCase starting with lowercase
• Constants: Use static let for type constants, let for instance constants
• Protocols: Use descriptive names, often ending with -able or describing capability

Example from /Users/onevcat/Sync/github/Kingfisher/Sources/General/Kingfisher.swift:

public protocol KingfisherCompatible: AnyObject { }
public protocol KingfisherCompatibleValue {}

Cross-Platform Type Aliases Copy Section

Kingfisher uses consistent cross-platform type aliases defined in /Users/onevcat/Sync/github/Kingfisher/Sources/General/Kingfisher.swift:

#if os(macOS)
public typealias KFCrossPlatformImage       = NSImage
public typealias KFCrossPlatformView        = NSView
public typealias KFCrossPlatformColor       = NSColor
public typealias KFCrossPlatformImageView   = NSImageView
public typealias KFCrossPlatformButton      = NSButton
#else
public typealias KFCrossPlatformImage       = UIImage
public typealias KFCrossPlatformColor       = UIColor
// ... additional platform-specific definitions
#endif

Sendable Compliance Copy Section

Modern Swift concurrency is enforced throughout the codebase:

public struct KingfisherWrapper: @unchecked Sendable {
    public let base: Base
    public init(_ base: Base) {
        self.base = base
    }
}

Common Implementation Patterns Copy Chapter

1. Namespace Wrapper Pattern Copy Section

The core pattern used throughout Kingfisher, implemented in /Users/onevcat/Sync/github/Kingfisher/Sources/General/Kingfisher.swift:

/// Wrapper for Kingfisher compatible types
public struct KingfisherWrapper: @unchecked Sendable {
    public let base: Base
    public init(_ base: Base) {
        self.base = base
    }
}

/// Protocol for types that can use .kf namespace
public protocol KingfisherCompatible: AnyObject { }

extension KingfisherCompatible {
    /// Gets a namespace holder for Kingfisher compatible types
    public var kf: KingfisherWrapper<Self> {
        get { return KingfisherWrapper(self) }
        set { }
    }
}

// Usage in extensions
extension KFCrossPlatformImage: KingfisherCompatible { }

2. Builder Pattern Copy Section

Fluent API implementation in /Users/onevcat/Sync/github/Kingfisher/Sources/General/KF.swift:

public enum KF {
    /// Creates a builder for a given URL
    public static func url(_ url: URL?, cacheKey: String? = nil) -> KF.Builder {
        source(url?.convertToSource(overrideCacheKey: cacheKey))
    }
}

extension KF {
    public class Builder: @unchecked Sendable {
        private let source: Source?
        private var _options = KingfisherParsedOptionsInfo(KingfisherManager.shared.defaultOptions)
        
        // Fluent configuration methods
        public func placeholder(_ image: KFCrossPlatformImage?) -> Self {
            self.placeholder = image
            return self
        }
    }
}

3. Options Pattern Copy Section

Comprehensive options system in /Users/onevcat/Sync/github/Kingfisher/Sources/General/KingfisherOptionsInfo.swift:

/// Represents the available option items
public enum KingfisherOptionsInfoItem: Sendable {
    case targetCache(ImageCache)
    case downloader(ImageDownloader)
    case transition(ImageTransition)
    case downloadPriority(Float)
    case forceRefresh
    case processor(any ImageProcessor)
    // ... many more options
}

/// Parsed options for internal use
public struct KingfisherParsedOptionsInfo: Sendable {
    public var targetCache: ImageCache? = nil
    public var downloader: ImageDownloader? = nil
    public var transition: ImageTransition = .none
    // ... corresponding properties
    
    public init(_ info: KingfisherOptionsInfo?) {
        guard let info = info else { return }
        for option in info {
            switch option {
            case .targetCache(let value): targetCache = value
            case .downloader(let value): downloader = value
            // ... handle all options
            }
        }
    }
}

4. Protocol-Oriented Design Copy Section

Example from /Users/onevcat/Sync/github/Kingfisher/Sources/Image/ImageProcessor.swift:

/// Protocol for image processing
public protocol ImageProcessor: Sendable {
    /// Identifier for caching and retrieval
    var identifier: String { get }
    
    /// Process the input item
    func process(item: ImageProcessItem, options: KingfisherParsedOptionsInfo) -> KFCrossPlatformImage?
}

extension ImageProcessor {
    /// Append processors in pipeline
    public func append(another: any ImageProcessor) -> any ImageProcessor {
        let newIdentifier = identifier.appending("|>\(another.identifier)")
        return GeneralProcessor(identifier: newIdentifier) { item, options in
            if let image = self.process(item: item, options: options) {
                return another.process(item: .image(image), options: options)
            } else {
                return nil
            }
        }
    }
}

5. Fluent Configuration with KFOptionSetter Copy Section

Protocol-based fluent API in /Users/onevcat/Sync/github/Kingfisher/Sources/General/KFOptionsSetter.swift:

@MainActor
public protocol KFOptionSetter {
    var options: KingfisherParsedOptionsInfo { get nonmutating set }
    var onFailureDelegate: Delegate<KingfisherError, Void> { get }
    var onSuccessDelegate: Delegate<RetrieveImageResult, Void> { get }
    var onProgressDelegate: Delegate<(Int64, Int64), Void> { get }
}

extension KFOptionSetter {
    public func targetCache(_ cache: ImageCache) -> Self {
        options.targetCache = cache
        return self
    }
    
    public func downloader(_ downloader: ImageDownloader) -> Self {
        options.downloader = downloader
        return self
    }
}

Development Workflows Copy Chapter

Setting Up Images for UI Components Copy Section

Common pattern for UIImageView/NSImageView (file: /Users/onevcat/Sync/github/Kingfisher/Sources/Extensions/ImageView+Kingfisher.swift):

// Basic usage
imageView.kf.setImage(with: url)

// With configuration
imageView.kf.setImage(
    with: url,
    placeholder: placeholderImage,
    options: [.transition(.fade(0.2)), .cacheMemoryOnly],
    completionHandler: { result in
        // Handle result
    }
)

Builder pattern approach:

KF.url(imageURL)
    .placeholder(placeholderImage)
    .fade(duration: 0.2)
    .cacheMemoryOnly()
    .onSuccess { result in
        print("Image loaded: \(result.image)")
    }
    .set(to: imageView)

Adding New Image Processors Copy Section

1. Create processor conforming to ImageProcessor protocol:

struct CustomProcessor: ImageProcessor {
    var identifier: String { "com.example.custom" }
    
    func process(item: ImageProcessItem, options: KingfisherParsedOptionsInfo) -> KFCrossPlatformImage? {
        // Implementation
    }
}

2. Add convenience method to KFOptionSetter (file: /Users/onevcat/Sync/github/Kingfisher/Sources/General/KFOptionsSetter.swift):

extension KFOptionSetter {
    public func customEffect() -> Self {
        appendProcessor(CustomProcessor())
    }
}

Extending Platform Support Copy Section

Add platform-specific extensions (pattern from existing platform extensions):

1. Update type aliases in /Users/onevcat/Sync/github/Kingfisher/Sources/General/Kingfisher.swift
2. Add compatibility conformance:

#if os(newOS)
extension NewOSImageView: KingfisherCompatible { }
#endif

3. Implement platform-specific extensions following the pattern in existing platform files

Cache Management Tasks Copy Section

Working with ImageCache (main class: /Users/onevcat/Sync/github/Kingfisher/Sources/Cache/ImageCache.swift):

// Configure cache
let cache = ImageCache(name: "custom")
cache.memoryStorage.config.totalCostLimit = 50 * 1024 * 1024 // 50MB
cache.diskStorage.config.sizeLimit = 200 * 1024 * 1024 // 200MB

// Use with options
imageView.kf.setImage(with: url, options: [.targetCache(cache)])

// Manual cache operations
cache.store(image, forKey: key)
cache.retrieveImage(forKey: key) { result in
    // Handle cached image
}

Reference Copy Chapter

File Organization Copy Section

Sources/
├── General/           # Core managers, options, data providers
│   ├── KingfisherManager.swift     # Central coordinator
│   ├── KF.swift                    # Builder pattern API
│   ├── Kingfisher.swift            # Core protocols and wrappers
│   ├── KingfisherOptionsInfo.swift # Options system
│   └── ImageSource/                # Data source abstractions
├── Networking/        # Download, prefetch, session management
│   ├── ImageDownloader.swift       # Network layer
│   ├── ImagePrefetcher.swift       # Batch prefetching
│   └── RetryStrategy.swift         # Retry logic
├── Cache/            # Multi-layer caching system
│   ├── ImageCache.swift            # Main cache interface
│   ├── MemoryStorage.swift         # Memory cache backend
│   └── DiskStorage.swift           # Disk cache backend
├── Image/            # Processing, filters, formats, transitions
│   ├── ImageProcessor.swift        # Processing protocols
│   ├── Filter.swift                # Built-in processors
│   └── ImageTransition.swift       # UI transition effects
├── Extensions/       # UIKit/AppKit integration
│   ├── ImageView+Kingfisher.swift  # Main UI extensions
│   └── UIButton+Kingfisher.swift   # Button extensions
├── SwiftUI/         # SwiftUI-specific components
│   ├── KFImage.swift               # SwiftUI image component
│   └── KFAnimatedImage.swift       # Animated SwiftUI component
├── Utility/         # Helper utilities and extensions
└── Views/           # Custom UI components

Naming Conventions Copy Section

• Manager classes: *Manager (e.g., KingfisherManager)
• Data providers: *Provider or *DataProvider (e.g., ImageDataProvider)
• Processors: *Processor or *ImageProcessor (e.g., BlurImageProcessor)
• Extensions: Type+Kingfisher.swift (e.g., UIButton+Kingfisher.swift)
• Protocols: Descriptive names often with -able suffix (KingfisherCompatible)
• Internal utilities: Plain descriptive names (CallbackQueue, Result)

Common Issues and Solutions Copy Section

Thread Safety: All public APIs are designed to be thread-safe. Use @MainActor for UI-related operations and @unchecked Sendable for wrapper types.

Memory Management: Kingfisher uses both memory and disk caching. Configure limits appropriately:

ImageCache.default.memoryStorage.config.totalCostLimit = 50 * 1024 * 1024
ImageCache.default.diskStorage.config.sizeLimit = 200 * 1024 * 1024

Platform Differences: Use platform-specific compilation directives and the provided cross-platform type aliases to ensure compatibility.

Testing: Use the testing utilities in /Users/onevcat/Sync/github/Kingfisher/Tests/KingfisherTests/KingfisherTestHelper.swift and follow the mocking patterns established in existing tests.

Performance: For large images, prefer DownsamplingImageProcessor over ResizingImageProcessor for better memory efficiency.

File: docs/files.md Copy Chapter

File Catalog - Kingfisher

Overview Copy Chapter

Kingfisher is a modern Swift library for loading and caching images, built with a modular structure and protocol-oriented design. The project clearly separates different concerns and uses a namespace pattern (.kf) to provide a consistent API for UIKit, AppKit, and SwiftUI. Its core components include KingfisherManager as the central coordinator, ImageDownloader for handling network tasks, ImageCache for a dual-layer caching system, and ImageProcessor for managing image transformation pipelines.

The project supports multiple platforms (iOS, macOS, tvOS, watchOS, visionOS) and uses Fastlane as its main build system. It employs the XCTest framework for testing and integrates the DocC documentation system. Files are organized based on functionality, with the Sources directory divided by modules, configuration files centrally managed, and Demo projects offering complete usage examples.

Core Source Files Copy Chapter

Primary Framework Components Copy Section

• Sources/General/KingfisherManager.swift - Central coordinator managing image loading workflow
• Sources/General/KF.swift - Main entry point providing builder pattern API for image tasks
• Sources/General/Kingfisher.swift - Core framework module with KingfisherCompatible protocol
• Sources/General/KingfisherOptionsInfo.swift - Configuration options container for all operations
• Sources/General/KingfisherError.swift - Error handling system with detailed error types
• Sources/General/KFOptionsSetter.swift - Options configuration builder for method chaining

Image Source and Data Providers Copy Section

• Sources/General/ImageSource/Resource.swift - URL resource definitions and transformations
• Sources/General/ImageSource/Source.swift - Abstract image source protocols and implementations
• Sources/General/ImageSource/ImageDataProvider.swift - Data provider protocol for custom image sources
• Sources/General/ImageSource/AVAssetImageDataProvider.swift - AVAsset image frame extraction
• Sources/General/ImageSource/PHPickerResultImageDataProvider.swift - Photo picker integration
• Sources/General/ImageSource/LivePhotoSource.swift - Live Photo support implementation

Network Layer Copy Section

• Sources/Networking/ImageDownloader.swift - HTTP image downloading with session management
• Sources/Networking/ImageDownloader+LivePhoto.swift - Live Photo downloading extensions
• Sources/Networking/ImageDownloaderDelegate.swift - Download progress and completion delegation
• Sources/Networking/SessionDelegate.swift - URLSession delegate handling authentication and redirects
• Sources/Networking/SessionDataTask.swift - Custom data task wrapper with cancellation support
• Sources/Networking/ImagePrefetcher.swift - Batch image prefetching for performance optimization
• Sources/Networking/RequestModifier.swift - HTTP request modification protocols
• Sources/Networking/ImageModifier.swift - Response image modification protocols
• Sources/Networking/RedirectHandler.swift - HTTP redirect handling strategies
• Sources/Networking/RetryStrategy.swift - Failed request retry logic and policies
• Sources/Networking/AuthenticationChallengeResponsable.swift - Authentication challenge handling
• Sources/Networking/ImageDataProcessor.swift - Raw image data processing pipeline

Caching System Copy Section

• Sources/Cache/ImageCache.swift - Dual-layer (memory + disk) caching coordinator
• Sources/Cache/MemoryStorage.swift - In-memory LRU cache with automatic cleanup
• Sources/Cache/DiskStorage.swift - Persistent disk storage with expiration policies
• Sources/Cache/Storage.swift - Abstract storage protocols and configurations
• Sources/Cache/CacheSerializer.swift - Image serialization for disk persistence
• Sources/Cache/FormatIndicatedCacheSerializer.swift - Format-aware image serialization

Image Processing and Transformation Copy Section

• Sources/Image/Image.swift - Cross-platform image type definitions and utilities
• Sources/Image/ImageProcessor.swift - Image transformation and processing pipeline
• Sources/Image/Filter.swift - Built-in image filters (blur, tint, overlay, etc.)
• Sources/Image/ImageFormat.swift - Image format detection and handling
• Sources/Image/ImageDrawing.swift - Core graphics drawing utilities and extensions
• Sources/Image/ImageTransition.swift - View transition animations for image loading
• Sources/Image/ImageProgressive.swift - Progressive JPEG loading implementation
• Sources/Image/GIFAnimatedImage.swift - GIF animation support and playback
• Sources/Image/GraphicsContext.swift - Graphics context management and utilities
• Sources/Image/Placeholder.swift - Placeholder image definitions and protocols

Platform Implementation Files Copy Chapter

UIKit Extensions Copy Section

• Sources/Extensions/ImageView+Kingfisher.swift - UIImageView integration with .kf namespace
• Sources/Extensions/UIButton+Kingfisher.swift - UIButton background/image loading support
• Sources/Extensions/NSTextAttachment+Kingfisher.swift - Text attachment image loading

AppKit Extensions Copy Section

• Sources/Extensions/NSButton+Kingfisher.swift - macOS NSButton image loading integration
• Sources/Extensions/HasImageComponent+Kingfisher.swift - Generic image component protocol

Cross-Platform Extensions Copy Section

• Sources/Extensions/PHLivePhotoView+Kingfisher.swift - Live Photo view integration
• Sources/Extensions/CPListItem+Kingfisher.swift - CarPlay list item support

SwiftUI Components Copy Section

• Sources/SwiftUI/KFImage.swift - Main SwiftUI image view component
• Sources/SwiftUI/KFAnimatedImage.swift - Animated image support for SwiftUI
• Sources/SwiftUI/KFImageOptions.swift - SwiftUI-specific configuration options
• Sources/SwiftUI/KFImageProtocol.swift - Shared protocol for KF SwiftUI components
• Sources/SwiftUI/KFImageRenderer.swift - SwiftUI view rendering and update logic
• Sources/SwiftUI/ImageBinder.swift - Binding layer between SwiftUI and Kingfisher core
• Sources/SwiftUI/ImageContext.swift - SwiftUI image loading context management

Custom Views Copy Section

• Sources/Views/AnimatedImageView.swift - Custom animated image view for GIF playback
• Sources/Views/Indicator.swift - Loading indicator views and protocols

Build System Files Copy Chapter

Package Management Copy Section

• Package.swift - Swift Package Manager manifest with dependencies and targets
• [email protected] - Swift 5.9 compatibility package manifest
• Kingfisher.podspec - CocoaPods specification for distribution
• Gemfile - Ruby dependencies for Fastlane and build tools
• Gemfile.lock - Locked Ruby gem versions for reproducible builds

Fastlane Build Automation Copy Section

• fastlane/Fastfile - Main Fastlane configuration with lanes for testing, building, and releasing
• fastlane/actions/extract_current_change_log.rb - Extracts current version changelog
• fastlane/actions/git_commit_all.rb - Git commit automation with custom messages
• fastlane/actions/sync_build_number_to_git.rb - Synchronizes build numbers with git commits
• fastlane/actions/update_change_log.rb - Automated changelog management
• fastlane/README.md - Fastlane documentation and usage instructions

Xcode Project Files Copy Section

• Kingfisher.xcodeproj/ - Main Xcode project with targets and build settings
• Kingfisher.xcworkspace/ - Xcode workspace for integrated development
• Demo/Kingfisher-Demo.xcodeproj/ - Demo application Xcode project

Configuration Files Copy Chapter

Framework Configuration Copy Section

• Sources/Info.plist - Framework bundle information and version metadata
• Sources/PrivacyInfo.xcprivacy - Privacy manifest for App Store compliance

Development Assets Copy Section

• images/ - Sample images for testing and demo applications
  • kingfisher-1.jpg through kingfisher-10.jpg - Test image assets
  • logo.png - Project logo and branding
• Tests/KingfisherTests/dancing-banana.gif - GIF test asset for animation testing
• Tests/KingfisherTests/single-frame.gif - Single-frame GIF for edge case testing

Demo Applications Copy Section

• Demo/Demo/Kingfisher-Demo/ - iOS demo app showcasing all features
  • ViewControllers/ - Various demo screens (GIF, transitions, processors, etc.)
  • SwiftUIViews/ - SwiftUI demonstration views and regression tests
• Demo/Demo/Kingfisher-macOS-Demo/ - macOS demo application
• Demo/Demo/Kingfisher-tvOS-Demo/ - Apple TV demo application
• Demo/Demo/Kingfisher-watchOS-Demo/ - watchOS demo application

Git and CI Configuration Copy Section

• pre-change.yml - Pre-commit hook configuration for code quality
• .gitignore - Git ignore patterns for build artifacts and dependencies

Utility and Helper Files Copy Chapter

Core Utilities Copy Section

• Sources/Utility/ExtensionHelpers.swift - Cross-platform compatibility helpers
• Sources/Utility/CallbackQueue.swift - Thread-safe callback queue management
• Sources/Utility/Box.swift - Reference wrapper for value types
• Sources/Utility/Result.swift - Result type utilities and extensions
• Sources/Utility/Delegate.swift - Weak delegate wrapper to prevent retain cycles
• Sources/Utility/Runtime.swift - Runtime reflection and dynamic dispatch utilities
• Sources/Utility/DisplayLink.swift - Cross-platform display link abstraction
• Sources/Utility/SizeExtensions.swift - CGSize manipulation and calculations
• Sources/Utility/String+SHA256.swift - String hashing for cache key generation

Test Infrastructure Copy Section

• Tests/KingfisherTests/KingfisherTestHelper.swift - Shared testing utilities and mocks
• Tests/KingfisherTests/Utils/StubHelpers.swift - HTTP stubbing helpers for network tests
• Tests/Dependency/Nocilla/ - HTTP mocking framework for isolated testing

Documentation System Copy Section

• Sources/Documentation.docc/ - DocC documentation bundle
  • Documentation.md - Main documentation entry point
  • GettingStarted.md - Quick start guide for new users
  • Tutorials/ - Step-by-step tutorials for UIKit and SwiftUI
  • CommonTasks/ - Task-oriented documentation for common use cases
  • Topics/ - Advanced topic guides (prefetching, indicators, etc.)
  • Resources/ - Documentation assets, images, and code samples

Reference Copy Chapter

File Organization Patterns Copy Section

• Modular Structure: Core functionality separated into logical modules (General, Networking, Cache, Image, etc.)
• Platform Abstraction: Cross-platform code in core modules, platform-specific extensions separate
• Protocol-Oriented: Heavy use of protocols for customization and testing
• Namespace Pattern: All public APIs accessed through .kf property extension

Naming Conventions Copy Section

• Files: PascalCase with descriptive names indicating functionality
• Protocols: Suffix with -able for capabilities (e.g., AuthenticationChallengeResponsable)
• Extensions: Platform prefix for clarity (e.g., UIButton+Kingfisher.swift)
• Tests: Mirror source structure with Tests suffix

Dependency Relationships Copy Section

• Core Dependencies: Foundation, UIKit/AppKit conditionally imported
• SwiftUI Module: Depends on core modules but isolated for optional usage
• Extensions: Depend on core but platform-specific
• Test Dependencies: Isolated with Nocilla for HTTP mocking
• Build Dependencies: Fastlane for automation, Ruby gems for tooling

Key Integration Points Copy Section

• KingfisherCompatible Protocol: Entry point for all functionality via .kf namespace
• Options System: Centralized configuration through KingfisherOptionsInfo
• Result Types: Consistent error handling with Result<Success, KingfisherError>
• Callback Queues: Thread-safe completion handling across all async operations

File: docs/issue-2495-analysis.md Copy Chapter

Issue #2495 Analysis: Disk Cache Deserialization Cannot Be Cancelled

1. Issue Overview Copy Chapter

Issue: #2495 - Images loading from cache are not canceled
Reporter: FaizanDurrani
Status: Open

Symptom Copy Section

When scrolling quickly through a large collection of images, memory usage explodes (>1 GB). The reporter uses KingfisherWebP and observes that ImageCache.retrieveImageInDiskCache is called for every displayed item, even after imageView.kf.cancelDownloadTask() is invoked.

Instruments Evidence Copy Section

The attached Instruments Allocations screenshot shows:

• Memory peak ~630 MB during fast scrolling
• Heaviest allocation stack:
  • ImageCache.retrieveImageInDiskCache(forKey:options:callbackQueue:completionHandler:) — 218.55 MB
  • KingfisherWrapper.image(webpData:options:) — 181.09 MB
  • WebP decode + CGImageCreate calls downstream

The majority of memory is consumed by WebP deserialization, not by disk I/O itself.

2. Root Cause Analysis Copy Chapter

The problem has two layers:

Layer 1: Cache Retrieval Is Not Cancellable Copy Section

cancelDownloadTask() calls DownloadTask.cancel(), which only cancels the network download (SessionDataTask.cancel(token:) in ImageDownloader.swift:121-124).

For images that hit the disk cache, KingfisherManager.retrieveImage returns nil at line 444 — there is no DownloadTask to cancel. Once retrieveImageInDiskCache dispatches its block to ioQueue, the entire chain (disk read → deserialization → memory promotion → callback) runs to completion with no interruption point.

Layer 2: Eager Disk-to-Memory Promotion Copy Section

Kingfisher's cache architecture is designed as "eager read into memory":

1. ImageCache.retrieveImage (line 608-655) checks memory first, then falls back to disk.
2. On disk hit, the image is fully deserialized via CacheSerializer.image(with:data:options:) on ioQueue (line 738).
3. The deserialized image is unconditionally stored into memory cache via store(image, toDisk: false) (line 641-645).
4. There is no lazy decode path, no thumbnail downsampling, and no option to skip memory promotion.

During fast scrolling, each reused cell triggers a new setImage call. The previous cell's disk cache retrieval is already enqueued on the serial ioQueue. With N cells scrolled through rapidly, N deserialization blocks queue up. WebP decoding is particularly expensive — each decode allocates significant memory. The combined allocations exceed NSCache's eviction speed, causing the memory spike.

Why Existing Mechanisms Don't Help Copy Section

3. Proposed Solution Copy Chapter

Approach: Source Task Identifier Check Before Deserialization Copy Section

Leverage the existing Source.Identifier / taskIdentifier mechanism — which already works at the view layer — and extend it into the cache retrieval path. The check is inserted before the expensive deserialization step, skipping decode for tasks that are no longer relevant.

Key Properties Copy Section

• No public API changes — all modifications are internal
• Backward compatible — direct KingfisherManager callers are unaffected (checker is nil)
• Completion handler contract preserved — every setImage call produces exactly one completion callback
• Worst case identical to current behavior — if the check doesn't fire in time, the decode proceeds as it does today

Changes Required Copy Section

3.1 `KingfisherParsedOptionsInfo` — New Internal Property

Add a closure property that flows through the options chain:

var sourceTaskIdentifierChecker: (@Sendable () -> Bool)?

Returns true if the task is still current, false if it has been superseded. This property is internal — not exposed in the public KingfisherOptionsInfoItem enum.

3.2 `KingfisherManager.retrieveImage` — Store Checker in Options

Currently referenceTaskIdentifierChecker (line 306) is only applied to onDataReceived side effects (line 329-332). Add one line to also store it in options:

if let checker = referenceTaskIdentifierChecker {
    options.onDataReceived?.forEach {
        $0.onShouldApply = checker
    }
    options.sourceTaskIdentifierChecker = checker  // NEW
}

This ensures the checker propagates to ImageCache via the options struct.

3.3 `ImageCache.retrieveImageInDiskCache` — Two Check Points

Insert checks before disk read and before deserialization:

/* Detailed source-code truncated for AI context efficiency. */

Returning .success(nil) uses the same semantics as "image not found on disk", which is safely handled by all upstream callers.

3.4 `KingfisherManager.retrieveImageFromCache` — Prevent Spurious Download (Path 2 Only)

retrieveImageFromCache has two code paths:

• Path 1 (line 639-697): Processed image lookup. On .none result, calls completionHandler(.failure(.imageNotExisting)). Since retrieveImageFromCache already returned true synchronously, no download is triggered. No change needed.

• Path 2 (line 716-793): Original image fallback with custom processor. On .none result, calls self.loadAndCacheImage(...) (line 732) — this does trigger a download. Add a check here:

guard let image = cacheResult.image else {
    // NEW: Task is stale — report error instead of downloading.
    if let checker = options.sourceTaskIdentifierChecker, !checker() {
        let error = KingfisherError.cacheError(reason: .imageNotExisting(key: key))
        options.callbackQueue.execute { completionHandler?(.failure(error)) }
        return
    }

    if options.onlyFromCache {
        let error = KingfisherError.cacheError(reason: .imageNotExisting(key: key))
        options.callbackQueue.execute { completionHandler?(.failure(error)) }
    } else {
        let task = self.loadAndCacheImage(
            source: source,
            context: context,
            completionHandler: completionHandler
        )
        downloadTaskUpdated?(task?.value)
    }
    return
}

Summary of File Changes Copy Section

Total: ~17 lines of effective code.

4. Timing and Behavior Simulation Copy Chapter

Scenario A: Fast Scrolling (Primary Problem Case) Copy Section

A cell is reused 5 times within one layout pass. All setImage calls complete on the main thread before the serial ioQueue processes any block.

Main thread (single runloop pass):
  cellForItem → cell X: setImage(url_1), X.taskId = 101, dispatch block_1 to ioQueue
  cellForItem → cell X: setImage(url_5), X.taskId = 102, dispatch block_2 to ioQueue
  cellForItem → cell X: setImage(url_9), X.taskId = 103, dispatch block_3 to ioQueue
  cellForItem → cell X: setImage(url_13), X.taskId = 104, dispatch block_4 to ioQueue
  cellForItem → cell X: setImage(url_17), X.taskId = 105, dispatch block_5 to ioQueue
                                                                         ↕ main thread yields

ioQueue (serial, starts processing):
  block_1: CHECK 1 → X.taskId==101? → 105≠101 → SKIP (no disk read, no decode)
  block_2: CHECK 1 → X.taskId==102? → 105≠102 → SKIP
  block_3: CHECK 1 → X.taskId==103? → 105≠103 → SKIP
  block_4: CHECK 1 → X.taskId==104? → 105≠104 → SKIP
  block_5: CHECK 1 → X.taskId==105? → 105==105 → read disk → CHECK 2 → still valid → DECODE ✓

Result: 4 out of 5 decodes skipped. Only the actually-needed image is decoded.
Current behavior: All 5 images decoded, all promoted to memory, 4 results discarded at view layer.
Check hit rate: (N-1)/N → approaches 100% with faster scrolling.

Scenario B: Moderate Scrolling Copy Section

User scrolls at a pace where each cell stays visible for ~200ms. Decode takes ~100ms per image.

Main thread:
  t=0ms    setImage(url_1), X.taskId = 101, dispatch block_1

ioQueue:
  t=5ms    block_1: CHECK 1 → 101==101 ✓ → read disk (10ms)
  t=15ms   CHECK 2 → 101==101 ✓ → decode (100ms)
  t=115ms  decode complete → store to memory → callback

Main thread:
  t=200ms  cell reuse, setImage(url_5), X.taskId = 102, dispatch block_2

Result: Decode completes before cell reuse. Check does not fire.
Current behavior: Identical — image was needed and displayed.
Impact: None — and none needed, since one-at-a-time decode doesn't cause memory pressure.

Scenario C: Moderate Scrolling with Large File Copy Section

Same pace as B, but a very large WebP file takes 300ms to read from disk.

Main thread:
  t=0ms    setImage(url_1), X.taskId = 101, dispatch block_1

ioQueue:
  t=5ms    block_1: CHECK 1 → 101==101 ✓ → start disk read (300ms)

Main thread:
  t=200ms  cell reuse, setImage(url_5), X.taskId = 102

ioQueue:
  t=305ms  disk read complete → CHECK 2 → 101==102? → 101≠102 → SKIP decode ✓

Result: CHECK 2 catches the stale task after a slow disk read. Decode skipped.
Current behavior: Full decode runs (expensive), result discarded at view layer.
This is where the two-check design pays off — CHECK 1 was valid at dispatch time, but CHECK 2 catches the change.

Scenario D: Multiple Visible Cells (No Reuse) Copy Section

10 cells appear simultaneously on initial load. Each cell has a different image, no cell reuse occurs.

Main thread:
  cell A: setImage(url_1), A.taskId = 101
  cell B: setImage(url_2), B.taskId = 102
  ...
  cell J: setImage(url_10), J.taskId = 110

ioQueue:
  block for cell A: CHECK → A.taskId==101? → 101==101 ✓ → decode
  block for cell B: CHECK → B.taskId==102? → 102==102 ✓ → decode
  ...
  block for cell J: CHECK → J.taskId==110? → 110==110 ✓ → decode

Result: All 10 images decoded. This is correct — all 10 are needed.
Current behavior: Identical.
Impact: None. The check is per-cell (each cell has its own taskIdentifier), so concurrent requests for different cells don't interfere with each other.

Scenario E: Fast Scrolling with Custom Processor (Path 2) Copy Section

User has a custom ImageProcessor. Original image is cached on disk, processed version is not. Cell reuses rapidly.

Main thread:
  setImage(url_1, processor: blur), X.taskId = 101
  setImage(url_5, processor: blur), X.taskId = 102

retrieveImageFromCache:
  Path 1: processed image not cached → validCache = false
  Path 2: original image cached → canUseOriginalImageCache = true

  originalCache.retrieveImage → ioQueue:
    block_1: CHECK → 101==102? → SKIP decode → .success(nil)

  Path 2 callback:
    cacheResult.image == nil
    → CHECK: 101==102? → stale
    → completionHandler(.failure(.imageNotExisting))   ← no download triggered ✓

  View layer:
    issuedIdentifier(101) ≠ taskIdentifier(102) → .notCurrentSourceTask
    completionHandler(.failure(.notCurrentSourceTask)) ← user gets callback ✓

Without the path 2 fix: loadAndCacheImage would be called, triggering a network download that is ultimately discarded.

5. Completion Handler Contract Verification Copy Chapter

Contract: Every setImage call produces exactly one completion callback.

For the "skipped" task (stale identifier): Copy Section

retrieveImageInDiskCache → .success(nil)          // skipped decode
    ↓
ImageCache.retrieveImage → .success(.none)         // treated as "not found"
    ↓
retrieveImageFromCache:
  Path 1 → completionHandler(.failure(.imageNotExisting))    ✅ called
  Path 2 → checker prevents download,
           completionHandler(.failure(.imageNotExisting))    ✅ called
    ↓
handler (line 386) → failCurrentSource → completionHandler(.failure(...))
    ↓
View extension (line 331):
  issuedIdentifier ≠ taskIdentifier →
  completionHandler(.failure(.notCurrentSourceTask))         ✅ user receives callback

For the "current" task (valid identifier): Copy Section

Behavior is identical to today — full decode, memory promotion, success callback. No changes in this path.

6. Risk Assessment Copy Chapter

6.1 Thread Safety of `taskIdentifier` Access Copy Section

Status: Pre-existing issue, not introduced by this change.

The checker closure { issuedIdentifier == self.taskIdentifier } reads taskIdentifier (associated object on UIImageView) from ioQueue, while writes happen on @MainActor. The associated object uses OBJC_ASSOCIATION_RETAIN_NONATOMIC.

Mitigation factors:

• objc_getAssociatedObject / objc_setAssociatedObject use an internal lock in the ObjC runtime (AssociationsManager mutex). Memory access is serialized at the runtime level.
• The value is wrapped in Box. After reading the Box reference, we immediately extract the UInt value (copy semantics). No retained reference escapes.
• The same pattern already exists in onShouldApply for ImageProgressiveProvider (called from background decoder thread).

Worst case of torn read:

• Read old value (checker thinks task is still valid) → proceed with decode → same as current behavior
• Read new value (checker thinks task is stale) → skip a decode that was actually still needed → cell shows placeholder until the truly-current task completes

Recommendation: Consider changing OBJC_ASSOCIATION_RETAIN_NONATOMIC to OBJC_ASSOCIATION_RETAIN in a separate PR, independent of this optimization. This would make the contract explicit without affecting performance (associated object access is already locked).

6.2 Spurious `.imageNotExisting` Error Propagation Copy Section

When a skipped task returns .success(nil), it becomes .imageNotExisting upstream. This error flows through handler → failCurrentSource (line 352-383).

failCurrentSource checks:

1. error.isTaskCancelled (line 354) — no, this is a cache error, not a cancellation error. Won't short-circuit.
2. error.isLowDataModeConstrained (line 359) — no. Won't trigger low-data-mode fallback.
3. retrievingContext.popAlternativeSource() (line 369) — if alternative sources are configured, the next source will be tried.

Impact: If a user configures alternativeSources, a skipped task may trigger retrieval from the next alternative source. This retrieval result will be discarded at the view layer (stale taskIdentifier), but it wastes a network request or cache lookup.

Severity: Low. alternativeSources is a rarely-used feature. The wasted work is bounded (one alternative attempt that gets discarded). The exact same waste occurs today when a network download completes for a stale task.

Possible future improvement: Introduce a dedicated CacheErrorReason.taskCancelled case so that failCurrentSource short-circuits at line 354. This would require adding a case to the public KingfisherError.CacheErrorReason enum — a source-breaking change if users have exhaustive switches. Could be considered for the next major version.

6.3 Already-Running Decode Cannot Be Interrupted Copy Section

Once cacheSerializer.image(with:data:options:) begins execution, it runs to completion. There is no mid-decode cancellation.

Mitigating factor: The ioQueue is serial. At most one decode runs at any time. The memory consumed by a single in-flight decode is bounded and manageable. The issue in #2495 is caused by dozens of decodes queuing up and running sequentially while their decoded images accumulate in memory — our check prevents the queue from growing unboundedly.

6.4 `loadDiskFileSynchronously` Mode Copy Section

When loadDiskFileSynchronously is true, the loading queue is .untouch (caller's thread, typically main). In this case:

• CHECK 1 runs on the main thread synchronously — taskIdentifier was just set, so the check always passes.
• The disk read and decode run synchronously on the main thread, blocking the runloop. No opportunity for cell reuse.

Impact: No behavior change for synchronous mode. This is expected — synchronous mode is inherently non-cancellable.

6.5 Direct `KingfisherManager` / `ImageCache` API Users Copy Section

Users who call KingfisherManager.shared.retrieveImage(with:options:completionHandler:) or ImageCache.default.retrieveImage(forKey:...) directly:

• sourceTaskIdentifierChecker is never set (it's only populated from the view extension path).
• All checks evaluate to if let checker = nil → skip → original behavior.

Impact: None. Full backward compatibility.

7. Summary Copy Chapter

What This Fix Achieves Copy Section

• Skips expensive deserialization for disk-cached images when the requesting view has already moved on to a different image
• Prevents spurious network downloads when a cancelled cache lookup for a custom-processed image returns "not found"
• Preserves the completion handler contract — every setImage always results in exactly one completion callback

What This Fix Does NOT Achieve Copy Section

• Cannot interrupt a decode that is already in progress (inherent limitation of CacheSerializer protocol)
• Does not add a first-class cancellation API for cache lookups (would require public API changes)
• Does not address the taskIdentifier data race (pre-existing, should be fixed independently)
• Does not change the eager disk-to-memory promotion design (a larger architectural topic)

Estimated Effectiveness Copy Section

8. Implementation Plan Copy Chapter

Step 1: Add `sourceTaskIdentifierChecker` to `KingfisherParsedOptionsInfo` Copy Section

File: Sources/General/KingfisherOptionsInfo.swift
Location: Line 420, after onDataReceived (the other internal property)

Add:

var onDataReceived: [any DataReceivingSideEffect]? = nil
var sourceTaskIdentifierChecker: (@Sendable () -> Bool)? = nil  // NEW

This is an internal property (no public modifier), matching the pattern of onDataReceived. It does not need handling in the init(_ info:) switch since it is never set from KingfisherOptionsInfoItem.

Verification: Build succeeds. No public API surface change.

Step 2: Store `referenceTaskIdentifierChecker` into options Copy Section

File: Sources/General/KingfisherManager.swift
Location: Line 329-333, inside retrieveImage(with:options:...referenceTaskIdentifierChecker:...)

Change from:

if let checker = referenceTaskIdentifierChecker {
    options.onDataReceived?.forEach {
        $0.onShouldApply = checker
    }
}

To:

if let checker = referenceTaskIdentifierChecker {
    options.onDataReceived?.forEach {
        $0.onShouldApply = checker
    }
    options.sourceTaskIdentifierChecker = checker
}

This one-line addition causes the checker to propagate through RetrievingContext.options into every downstream call that receives KingfisherParsedOptionsInfo, including ImageCache.retrieveImage and retrieveImageInDiskCache.

Verification: Build succeeds. Existing tests pass — no behavioral change yet.

Step 3: Insert cancellation checks in `retrieveImageInDiskCache` Copy Section

File: Sources/Cache/ImageCache.swift
Location: Line 730-749, the loadingQueue.execute block in the internal retrieveImageInDiskCache

Change from:

loadingQueue.execute {
    do {
        var image: KFCrossPlatformImage? = nil
        if let data = try self.diskStorage.value(
            forKey: computedKey,
            forcedExtension: options.forcedExtension,
            extendingExpiration: options.diskCacheAccessExtendingExpiration
        ) {
            image = options.cacheSerializer.image(with: data, options: options)
        }
        if options.backgroundDecode {
            image = image?.kf.decoded(scale: options.scaleFactor)
        }
        callbackQueue.execute { [image] in completionHandler(.success(image)) }
    } catch let error as KingfisherError {
        callbackQueue.execute { completionHandler(.failure(error)) }
    } catch {
        assertionFailure("The internal thrown error should be a `KingfisherError`.")
    }
}

To:

loadingQueue.execute {
    // CHECK 1: For blocks queued behind others on the serial ioQueue,
    // the task is likely already stale by the time execution begins.
    if let checker = options.sourceTaskIdentifierChecker, !checker() {
        callbackQueue.execute { completionHandler(.success(nil)) }
        return
    }

    do {
        var image: KFCrossPlatformImage? = nil
        if let data = try self.diskStorage.value(
            forKey: computedKey,
            forcedExtension: options.forcedExtension,
            extendingExpiration: options.diskCacheAccessExtendingExpiration
        ) {
            // CHECK 2: Disk read completed, but deserialization has not started.
            // Catches staleness that occurred during a slow disk read.
            if let checker = options.sourceTaskIdentifierChecker, !checker() {
                callbackQueue.execute { completionHandler(.success(nil)) }
                return
            }
            image = options.cacheSerializer.image(with: data, options: options)
        }
        if options.backgroundDecode {
            image = image?.kf.decoded(scale: options.scaleFactor)
        }
        callbackQueue.execute { [image] in completionHandler(.success(image)) }
    } catch let error as KingfisherError {
        callbackQueue.execute { completionHandler(.failure(error)) }
    } catch {
        assertionFailure("The internal thrown error should be a `KingfisherError`.")
    }
}

Why two checks:

• CHECK 1 fires for queued blocks whose task became stale while waiting. Skips both disk I/O and decode. This is the high-hit-rate path during fast scrolling.
• CHECK 2 fires when disk read was slow (large file) and the task became stale during the read. Skips only decode.

Verification: Build succeeds. Test with a fast-scrolling collection view and Instruments to confirm decode skipping.

Step 4: Prevent spurious download in `retrieveImageFromCache` path 2 Copy Section

File: Sources/General/KingfisherManager.swift
Location: Line 724-738, inside the originalCache.retrieveImage callback in retrieveImageFromCache

Change from:

result.match(
    onSuccess: { cacheResult in
        guard let image = cacheResult.image else {
            if options.onlyFromCache {
                let error = KingfisherError.cacheError(reason: .imageNotExisting(key: key))
                options.callbackQueue.execute { completionHandler?(.failure(error)) }
            } else {
                let task = self.loadAndCacheImage(
                    source: source,
                    context: context,
                    completionHandler: completionHandler
                )
                downloadTaskUpdated?(task?.value)
            }
            return
        }

To:

result.match(
    onSuccess: { cacheResult in
        guard let image = cacheResult.image else {
            // If the task is stale (cancelled by a newer setImage call),
            // report cache miss instead of triggering a network download.
            if let checker = options.sourceTaskIdentifierChecker, !checker() {
                let error = KingfisherError.cacheError(reason: .imageNotExisting(key: key))
                options.callbackQueue.execute { completionHandler?(.failure(error)) }
                return
            }

            if options.onlyFromCache {
                let error = KingfisherError.cacheError(reason: .imageNotExisting(key: key))
                options.callbackQueue.execute { completionHandler?(.failure(error)) }
            } else {
                let task = self.loadAndCacheImage(
                    source: source,
                    context: context,
                    completionHandler: completionHandler
                )
                downloadTaskUpdated?(task?.value)
            }
            return
        }

Why this is needed: Path 2 handles original-image fallback with custom processors. When the original image's decode is skipped (returning .none), the existing code falls through to loadAndCacheImage, triggering a network download. The check prevents this wasted request while still calling completionHandler to preserve the contract.

Verification: Build succeeds. Existing tests pass. For targeted testing: configure a custom ImageProcessor with disk-cached original images, fast-scroll, and verify no spurious network requests in Charles/Instruments.

Step 5: Testing Copy Section

Unit Tests

Add test cases in Tests/KingfisherTests/:

1. Cache retrieval skip on stale identifier: Set up a disk-cached image. Simulate a stale sourceTaskIdentifierChecker (returns false). Verify retrieveImageInDiskCache returns .success(nil) without invoking CacheSerializer.image(with:).

2. Completion handler contract: Call setImage, then immediately call setImage again on the same view. Verify the first call's completion receives .notCurrentSourceTask error.

3. Valid identifier proceeds normally: Set up a disk-cached image. Provide a checker that returns true. Verify the image is decoded and returned normally.

4. Path 2 download prevention: Configure a custom processor, cache only the original image on disk. Provide a stale checker. Verify loadAndCacheImage is NOT called and completion receives .imageNotExisting.

Manual / Integration Testing

• Instruments: Profile a fast-scrolling collection view with WebP images. Compare memory peak before and after the change.
• Functional: Verify images display correctly at all scrolling speeds. No blank or stuck cells.
• Edge cases: Test with loadDiskFileSynchronously = true, fromMemoryCacheOrRefresh = true, and alternativeSources configured.

Execution Order Copy Section

Step 1 (add property)
  └─ Step 2 (wire checker into options)
       └─ Step 3 (cache-level checks)   ── can be done in parallel ──  Step 4 (path 2 guard)
                                                                           │
                                                                       Step 5 (tests)

Steps 1→2 are prerequisites. Steps 3 and 4 are independent of each other. Step 5 should cover all changes.

Review From Codex Copy Chapter

Overall Assessment Copy Section

I agree with the root cause analysis in this document:

• The main issue is not cancelDownloadTask() itself, but that the disk-cache retrieval path has no cancellation point once work is enqueued.
• The current disk-hit behavior eagerly deserializes the image and then promotes it into memory cache, even when the requesting view has already moved on to another source.
• The existing taskIdentifier check at the view layer happens too late. It prevents stale results from being applied to the view, but it does not prevent the expensive decode work from already happening.

These points are consistent with the current implementation in:

• Sources/Extensions/ImageView+Kingfisher.swift
• Sources/General/KingfisherManager.swift
• Sources/Cache/ImageCache.swift
• Sources/Networking/ImageDownloader.swift

Main Concern With the Proposed Fix Copy Section

I do not recommend shipping the proposed solution exactly as written.

The main problem is that it represents a stale request as .success(nil) inside retrieveImageInDiskCache, which then becomes a normal cache miss (.none / .imageNotExisting) upstream.

That encoding leaks the wrong semantics into higher layers:

• ImageCache.retrieveImage(forKey:options:...) treats nil as a normal disk miss.
• KingfisherManager.retrieveImageFromCache then treats that result as an ordinary cache failure path.
• At the manager level, ordinary failures can still flow into retry logic or alternativeSources.

So the side effect is broader than only "path 2 may trigger a spurious download". Both retry and alternative-source logic can be activated by a stale request that should have been short-circuited as "no longer relevant", not "cache miss".

This is the strongest reason I would not merge the current proposal unchanged.

Thread-Safety Concern Copy Section

The document's thread-safety discussion is somewhat optimistic.

Today, the checker closure reads taskIdentifier from a background queue, while writes happen on @MainActor. The storage behind taskIdentifier is implemented with associated objects and OBJC_ASSOCIATION_RETAIN_NONATOMIC.

Changing that association to atomic might reduce some risk, but it does not really solve the larger issue: a background queue is still observing UI-associated state across actor boundaries.

If this optimization is added, I suggest tightening this part of the design as well, instead of relying on the current associated-object pattern more heavily than it already is.

Additional Observation Copy Section

The proposed check points are directionally correct, but there is one more cheap place worth checking:

• after disk read
• before serializer decode
• before backgroundDecode

The dominant cost for WebP is likely already inside the serializer path, so this does not change the main conclusion. Still, adding a final stale check before backgroundDecode is nearly free and keeps the behavior more consistent.

Recommended Direction Copy Section

I recommend keeping the overall approach, but changing the internal representation of the outcome.

Instead of encoding "stale request" as .success(nil) or .imageNotExisting, use an explicit internal stale state, for example an internal retrieval result such as:

enum DiskRetrievalResult {
    case image(KFCrossPlatformImage)
    case none
    case stale
}

Then:

• ImageCache can stop work early and report .stale internally.
• KingfisherManager can short-circuit .stale without entering retry logic.
• retrieveImageFromCache path 2 can avoid download fallback for stale work.
• completion behavior at the view layer remains unchanged, because the view will still eventually surface .notCurrentSourceTask for the outdated request.

This preserves the optimization benefit without polluting existing cache-miss semantics.

Recommended Checker Design Copy Section

I would also prefer that the checker read from a dedicated thread-safe token holder instead of reading the view's associated-object-backed taskIdentifier directly from a background queue.

Using sourceTaskIdentifierChecker as an internal option is fine. The weak point is not the propagation mechanism; it is the current state source used by the checker.

Memory-Model Note Copy Section

This issue is primarily about avoiding stale decode work, and that is worth fixing first.

However, the current memory spike is amplified by another design choice as well: on disk hit, the decoded image is unconditionally promoted back into memory cache. If memory pressure reports continue even after stale decode skipping is added, the next place to revisit is whether disk-hit promotion should always be eager.

That is a larger architectural question and should probably remain separate from the narrow fix for #2495.

Documentation Note Copy Section

One minor accuracy issue in the implementation plan: the file name should be Sources/General/KingfisherOptionsInfo.swift, not KingfisherOptionsInfoItems.swift.

Merge Recommendation Copy Section

My recommendation is:

1. Keep the idea of checking staleness before expensive disk-cache deserialization.
2. Do not encode stale work as a normal cache miss.
3. Introduce an internal explicit stale outcome and short-circuit it in KingfisherManager.
4. Tighten the checker state source so it does not depend on reading UI-associated state from a background queue.
5. Add regression tests for retry strategy and alternativeSources, not only for path 2 fallback.

With those adjustments, the fix looks worthwhile and technically sound. Without them, the current proposal is likely to reduce memory pressure in the target scenario, but it also introduces semantic leakage into error handling and recovery paths.

Response From Claude Copy Chapter

Overall Copy Section

The Codex review is thorough and technically accurate. All five recommendations are accepted and should be incorporated into the final implementation.

On the Main Concern (`.success(nil)` Semantic Leakage) Copy Section

This is the most valuable point in the review, and it identifies a flaw that our original analysis underestimated.

Section 6.2 of this document assessed the alternativeSources interaction as "Low" severity. That assessment was incomplete. The retry strategy interaction is worse: a stale request encoded as .imageNotExisting enters handler (KingfisherManager.swift:394), which consults retryStrategy. If the user has configured a retry strategy (e.g., DelayRetryStrategy(maxRetryCount: 3)), the stale request loops through startNewRetrieveTask → imageCachedType (still cached) → retrieveImage → ioQueue → checker (still stale) → .imageNotExisting → retry again, up to maxRetryCount times. Each cycle is individually cheap (the checker skips decode), but the loop is semantically wrong and wastes work.

The DiskRetrievalResult enum approach cleanly eliminates this. By distinguishing .stale from .none at the ImageCache boundary, KingfisherManager can short-circuit before entering retry or alternative-source logic. The additional complexity is minimal (~10 lines for the enum + ~10 lines for handling), and it makes the control flow explicit and correct.

On Thread Safety Copy Section

The review correctly notes that our thread-safety discussion is optimistic. The practical risk is indeed low — objc_getAssociatedObject uses an internal runtime lock, and the Box value is immediately copied — but "probably safe due to runtime implementation details" is not a strong engineering argument for a library consumed by thousands of apps.

More importantly, we are not introducing this pattern — the existing onShouldApply in ImageProgressiveProvider already reads taskIdentifier from a background thread. Our change would amplify the reliance on this pattern (every disk cache retrieval instead of only progressive loads), which makes the case for fixing it stronger.

A CancellationToken (~15 lines) replaces the cross-actor read with a lock-protected Bool. The checker becomes { !token.isCancelled } instead of { issuedIdentifier == self.taskIdentifier }. This is self-evidently correct and does not depend on ObjC runtime internals. It should be included in the initial PR rather than deferred, since the incremental cost is small and the design becomes clean from the start.

On `backgroundDecode` Check Copy Section

Agreed. decoded(scale:) forces bitmap rendering into a new context. The cost is secondary to WebP deserialization, but the check is nearly free and keeps the pattern consistent. Include it.

On Regression Tests Copy Section

The original test plan (Section 8, Step 5) covered the basic cases but missed two important scenarios:

1. Retry strategy with stale request: Verify that a stale disk cache retrieval does not enter the retry loop. With DiskRetrievalResult.stale, the handler should short-circuit before consulting retryStrategy.

2. Alternative sources with stale request: Verify that a stale result does not trigger popAlternativeSource(). The .stale result should bypass failCurrentSource entirely.

These should be added to the test plan.

On the Documentation Note Copy Section

Confirmed. Section 3.1 and the Summary table in Section 3 reference KingfisherOptionsInfoItems.swift. The correct file name is KingfisherOptionsInfo.swift. This will be corrected when the implementation plan is finalized.

Summary of Accepted Changes Copy Section

All five recommendations are accepted for the initial PR:

Total additional production code over the original proposal: ~35 lines. The overall change remains small and focused.

File: docs/project-overview.md Copy Chapter

Kingfisher Project Overview

Project Purpose Copy Chapter

Kingfisher is a powerful, pure-Swift library for downloading and caching images from the web. It provides an elegant, asynchronous API for managing remote images in iOS, macOS, tvOS, watchOS, and visionOS applications. The library handles the complete lifecycle of image loading - from network downloading to multi-layer caching (memory and disk), with built-in image processing capabilities and extensive platform-specific UI component integrations.

The framework follows a modular architecture with clear separation of concerns, allowing developers to use individual components (downloader, cache, processors) independently or as a unified solution. Through its namespace wrapper pattern (.kf property) and builder pattern (KF.url()), Kingfisher offers both UIKit and SwiftUI support with minimal code overhead.

Main Entry Points Copy Chapter

Core Configuration Copy Section

• Package.swift - Swift Package Manager manifest defining library targets and platform requirements
• Kingfisher.podspec - CocoaPods specification (version 8.3.2)
• Sources/General/Kingfisher.swift - Core type definitions and protocol declarations
• Sources/General/KingfisherManager.swift - Central coordinator managing download and cache operations

Primary APIs Copy Section

• Sources/General/KF.swift - Builder pattern entry point for fluent API
• Sources/Extensions/ImageView+Kingfisher.swift - UIImageView/NSImageView extensions
• Sources/SwiftUI/KFImage.swift - SwiftUI image component
• Sources/SwiftUI/KFAnimatedImage.swift - SwiftUI animated image support

Technology Stack Copy Chapter

Core Components Copy Section

• Image Downloading: Sources/Networking/ImageDownloader.swift - URLSession-based networking layer
• Cache System:
  • Sources/Cache/ImageCache.swift - Dual-layer cache coordinator
  • Sources/Cache/MemoryStorage.swift - In-memory cache implementation
  • Sources/Cache/DiskStorage.swift - Persistent disk storage
• Image Processing: Sources/Image/ImageProcessor.swift - Transformation pipeline with filters
• Format Support: Sources/Image/ImageFormat.swift - Multi-format detection (JPEG, PNG, GIF, WebP)

Platform Integrations Copy Section

• UIKit Extensions: Sources/Extensions/UIButton+Kingfisher.swift, Sources/Extensions/NSTextAttachment+Kingfisher.swift
• SwiftUI Components: Sources/SwiftUI/KFImageProtocol.swift, Sources/SwiftUI/ImageBinder.swift
• Specialized Views: Sources/Views/AnimatedImageView.swift, Sources/Extensions/PHLivePhotoView+Kingfisher.swift

Build & Testing Copy Section

• Fastlane: fastlane/Fastfile - Primary build automation
• Test Suite: Tests/KingfisherTests/ - XCTest-based unit tests with Nocilla HTTP stubbing
• Documentation: Sources/Documentation.docc/ - DocC integrated documentation

Platform Support Copy Chapter

Minimum Requirements Copy Section

• Swift: 5.9+ (Swift 6 strict concurrency ready)
• UIKit/AppKit:
  • iOS 13.0+ (#if os(iOS))
  • macOS 10.15+ (#if os(macOS))
  • tvOS 13.0+ (#if os(tvOS))
  • watchOS 6.0+ (#if os(watchOS))
  • visionOS 1.0+ (#if os(visionOS))
• SwiftUI: iOS 14.0+ / macOS 11.0+ / tvOS 14.0+ / watchOS 7.0+ / visionOS 1.0+

Platform-Specific Files Copy Section

• macOS: Sources/Extensions/NSButton+Kingfisher.swift - NSButton image loading
• iOS/tvOS: Sources/Extensions/UIButton+Kingfisher.swift - UIButton extensions
• watchOS: Sources/Extensions/WKInterfaceImage+Kingfisher.swift - WatchKit support
• CarPlay: Sources/Extensions/CPListItem+Kingfisher.swift - CarPlay list items (iOS 14.0+)
• tvOS: Sources/Extensions/TVMonogramView+Kingfisher.swift - Apple TV monogram views

File: docs/testing.md Copy Chapter

Kingfisher Testing Documentation

Overview Copy Chapter

Kingfisher's test suite is located in the Tests/KingfisherTests/ directory and provides comprehensive coverage for all major components of the library. The test suite uses XCTest framework with custom helper utilities and the Nocilla dependency for HTTP request stubbing.

Test Infrastructure Copy Section

• Test Framework: XCTest
• Network Mocking: Nocilla (located at Tests/Dependency/Nocilla/)
• Test Helper: Tests/KingfisherTests/KingfisherTestHelper.swift
• Stub Utilities: Tests/KingfisherTests/Utils/StubHelpers.swift
• Test Assets:
  • Tests/KingfisherTests/dancing-banana.gif - Animated GIF for testing
  • Tests/KingfisherTests/single-frame.gif - Single frame GIF for testing

Test Categories Copy Chapter

1. Core Component Tests Copy Section

Cache Layer Tests

• Tests/KingfisherTests/ImageCacheTests.swift - Tests for the main ImageCache functionality
• Tests/KingfisherTests/MemoryStorageTests.swift - Memory cache specific tests
• Tests/KingfisherTests/DiskStorageTests.swift - Disk storage specific tests
• Tests/KingfisherTests/StorageExpirationTests.swift - Cache expiration policy tests

Networking Tests

• Tests/KingfisherTests/ImageDownloaderTests.swift - Image downloading and session management
• Tests/KingfisherTests/ImagePrefetcherTests.swift - Batch image prefetching functionality
• Tests/KingfisherTests/DataReceivingSideEffectTests.swift - Data processing side effects

Manager Tests

• Tests/KingfisherTests/KingfisherManagerTests.swift - Central coordinator tests
• Tests/KingfisherTests/KingfisherOptionsInfoTests.swift - Configuration options tests

2. Image Processing Tests Copy Section

• Tests/KingfisherTests/ImageProcessorTests.swift - Image transformation pipeline tests
• Tests/KingfisherTests/ImageDrawingTests.swift - Image drawing and rendering tests
• Tests/KingfisherTests/ImageExtensionTests.swift - Core image extensions tests
• Tests/KingfisherTests/ImageModifierTests.swift - Request modifier tests

3. UI Integration Tests Copy Section

UIKit Tests

• Tests/KingfisherTests/ImageViewExtensionTests.swift - UIImageView extension tests
• Tests/KingfisherTests/UIButtonExtensionTests.swift - UIButton extension tests

AppKit Tests

• Tests/KingfisherTests/NSButtonExtensionTests.swift - NSButton extension tests (macOS)

4. Specialized Feature Tests Copy Section

• Tests/KingfisherTests/LivePhotoSourceTests.swift - Live Photo support tests
• Tests/KingfisherTests/ImageDataProviderTests.swift - Custom data provider tests
• Tests/KingfisherTests/RetryStrategyTests.swift - Network retry strategy tests
• Tests/KingfisherTests/StringExtensionTests.swift - String utility extension tests

Running Tests Copy Chapter

Using Fastlane Copy Section

# Install dependencies first
bundle install

# Run all tests across all platforms
bundle exec fastlane tests

# Expected output:
# [08:30:00]: ------------------------------
# [08:30:00]: --- Step: default_platform ---
# [08:30:00]: ------------------------------
# [08:30:00]: Driving the lane 'ios tests' 🚀
# [08:30:01]: ------------------
# [08:30:01]: --- Step: scan ---
# [08:30:01]: ------------------
# [08:30:01]: Running Tests: ▸ Touching Kingfisher.framework
# [08:30:45]: Test Succeeded

# Run tests for specific platform
bundle exec fastlane test destination:"platform=iOS Simulator,name=iPhone 15"
bundle exec fastlane test destination:"platform=macOS"
bundle exec fastlane test destination:"platform=tvOS Simulator,name=Apple TV"

# CI-specific test command (used in continuous integration)
DESTINATION="platform=iOS Simulator,name=iPhone 15,OS=17.5" bundle exec fastlane test_ci

# Build only (for watchOS where full testing isn't supported)
bundle exec fastlane build destination:"platform=watchOS Simulator,name=Apple Watch Series 9 (41mm)"

Using Xcode Copy Section

# Open workspace in Xcode
open Kingfisher.xcworkspace

# Then use Xcode's test navigator or press Cmd+U to run all tests
# Or use xcodebuild directly:
xcodebuild test -workspace Kingfisher.xcworkspace -scheme Kingfisher -destination "platform=iOS Simulator,name=iPhone 15"

Test File Organization Reference Copy Chapter

Directory Structure Copy Section

Tests/
├── Dependency/
│   └── Nocilla/              # HTTP stubbing framework
│       ├── LICENSE
│       ├── README.md
│       └── Nocilla/          # Nocilla source files
│           ├── Categories/   # NSData and NSString extensions
│           ├── DSL/          # Domain-specific language for stubbing
│           ├── Diff/         # Request diff utilities
│           ├── Hooks/        # HTTP client hooks (NSURLSession, etc.)
│           ├── Matchers/     # Request matching logic
│           ├── Model/        # HTTP request/response models
│           └── Stubs/        # Stub implementation
└── KingfisherTests/
    ├── Info.plist
    ├── KingfisherTestHelper.swift      # Main test helper utilities
    ├── KingfisherTests-Bridging-Header.h  # Objective-C bridging
    ├── Utils/
    │   └── StubHelpers.swift           # Network stubbing helpers
    ├── dancing-banana.gif              # Animated test image
    ├── single-frame.gif                # Static test image
    └── *Tests.swift                    # Individual test files

Build System Test Targets Copy Section

Xcode Scheme: Kingfisher.xcscheme

• Configured for testing on all supported platforms
• Includes code coverage collection
• Uses parallel testing when available

Fastlane Configuration: fastlane/Fastfile

• tests lane: Runs tests on all platforms
• test_ci lane: CI-specific testing with environment-based destination
• test lane: Core test execution with scan action
• build lane: Build-only verification (used for watchOS)

Platform Test Destinations:

• iOS: platform=iOS Simulator,name=iPhone 15,OS=17.5
• macOS: platform=macOS
• tvOS: platform=tvOS Simulator,name=Apple TV,OS=17.5
• watchOS: platform=watchOS Simulator,name=Apple Watch Series 9 (41mm),OS=10.5 (build only)

Test Helper Utilities Copy Section

The KingfisherTestHelper.swift provides:

• Pre-encoded test image data in various formats (PNG, JPEG, GIF, HEIC, MOV)
• Test URLs and keys for stubbing
• Cache cleanup utilities (cleanDefaultCache, clearCaches)
• Image comparison with tolerance (renderEqual)
• Timing utilities (delay)
• Platform-specific test helpers

The StubHelpers.swift provides:

• stub() - Create HTTP response stubs with custom data and headers
• delayedStub() - Create delayed response stubs for timing tests
• Network error stubbing capabilities

File: README-LLM.md Copy Chapter

Kingfisher

Kingfisher is a powerful, pure-Swift library for downloading and caching images from the web, providing elegant async APIs for iOS, macOS, tvOS, watchOS, and visionOS applications. The library handles the complete image lifecycle with multi-layer caching, built-in processing, and extensive UI component integrations.

Quick Start Copy Chapter

Core API Entry Points:

• Sources/General/KingfisherManager.swift - Central coordinator
• Sources/General/KF.swift - Builder pattern API (KF.url()...)
• Sources/Extensions/ImageView+Kingfisher.swift - UIKit/AppKit extensions
• Sources/SwiftUI/KFImage.swift - SwiftUI components

Essential Build Commands:

# Install dependencies and run all tests
bundle install && bundle exec fastlane tests

# Build for specific platform
swift build

# Full release workflow
bundle exec fastlane release version:X.X.X

Documentation Copy Chapter

For LLMs and Developers:

• Project Overview - What Kingfisher does, core purpose, technology stack, and platform support
• Architecture - System organization, component map, key files, and data flow with specific file references
• Build System - Swift Package Manager and Fastlane workflows, platform setup, and troubleshooting
• Testing - Test categories, running tests, and test infrastructure with file locations
• Development - Code style, implementation patterns, workflows, and common solutions
• Deployment - Package types, platform deployment, release management, and CI/CD
• File Catalog - Comprehensive file organization with specific file purposes and relationships

Configuration Files:

• Package.swift - Swift Package Manager manifest
• Kingfisher.podspec - CocoaPods specification
• fastlane/Fastfile - Build automation
• Sources/Documentation.docc/ - DocC documentation

Key Patterns:

• Namespace wrapper (.kf property) in Sources/General/Kingfisher.swift
• Builder pattern API in Sources/General/KF.swift
• Options system in Sources/General/KingfisherOptionsInfo.swift
• Protocol-oriented design throughout Sources/Image/ImageProcessor.swift

Requirements Copy Chapter

• Swift 5.9+ (Swift 6 strict concurrency ready)
• iOS 13.0+ / macOS 10.15+ / tvOS 13.0+ / watchOS 6.0+ / visionOS 1.0+
• SwiftUI support: iOS 14.0+ / macOS 11.0+ / tvOS 14.0+ / watchOS 7.0+ / visionOS 1.0+