Skip to content
Open
1 change: 1 addition & 0 deletions .scripts/generate-llms.py
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@
"Essentials/troubleshooting.md",
"Customization/ImageProcessing/image-processing.md",
"Customization/LoadingData/loading-data.md",
"Customization/LoadingData/retrying-requests.md",
"Performance/Caching/caching.md",
"Performance/Caching/cache-layers.md",
"Performance/Caching/accessing-caches.md",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,10 @@ let pipeline = ImagePipeline(delegate: AuthenticatedPipelineDelegate()) {

The method is called on every URL-based request, after resumable data headers are applied but before the request is passed to ``DataLoading``. Throwing an error cancels the request and surfaces the error as ``ImagePipeline/Error/dataLoadingFailed(error:)``. The hook is not called for requests that use a custom data fetch closure or that target local file resources.

## Retrying Failed Requests

Set ``ImagePipeline/Configuration-swift.struct/retryPolicy`` to have the pipeline retry the loads that fail for a reason that can go away. To learn more, see <doc:retrying-requests>.

## Monitoring Network Requests

The pipeline can be used with [Pulse](https://github.com/kean/Pulse) for monitoring network traffic.
Expand Down
140 changes: 140 additions & 0 deletions Documentation/Nuke.docc/Customization/LoadingData/retrying-requests.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
# Retrying Failed Requests

Recover from a dropped connection or a server having a bad moment without writing any loading code.

## Overview

Retries are off by default, because how long an image is worth waiting for is up to the app. To turn them on, set a ``ImagePipeline/RetryPolicy`` on the pipeline:

```swift
ImagePipeline.shared = ImagePipeline {
$0.retryPolicy = .default
}
```

With the default policy, a load that fails for a reason that can go away is tried two more times, about 0.5 s and 1 s apart. `LazyImage` and the other views need no changes: they stay in the loading state until the pipeline gets the image or gives up.

## What Gets Retried

The policy retries what a second attempt can fix:

- The URL errors that mean that the connection failed or dropped out, listed in ``ImagePipeline/RetryPolicy/retryableURLErrorCodes``
- The status codes `408`, `429`, `500`, `502`, `503`, and `504`, listed in ``ImagePipeline/RetryPolicy/retryableStatusCodes``

It leaves alone what would fail the same way again:

- The rest of the failed responses, such as a `404`
- A request that isn't idempotent, such as a `POST`
- A failure caused by Low Data Mode, or by a restriction on expensive networks
- A failure to decode or process an image: the same data would fail again
- A local resource

The policy recognizes the errors of ``DataLoader`` and `URLError`, whichever data loader or `data` closure they come from. To retry other errors, implement ``ImagePipeline/Delegate-swift.protocol/retryDecision(for:pipeline:)``.

## Changing the Policy

```swift
var policy = ImagePipeline.RetryPolicy.default
policy.maxRetryCount = 4
policy.backoff = .exponential(initial: 1, multiplier: 3)
policy.retryableStatusCodes.insert(404) // A CDN that takes a moment to catch up

let pipeline = ImagePipeline {
$0.retryPolicy = policy
}
```

The delays have ``ImagePipeline/RetryPolicy/jitter`` applied to them. When a host goes down, every image on the screen fails at the same time, and the jitter keeps them from all coming back at the same time.

If a response has a `Retry-After` header, the pipeline waits for at least as long as it says. If the server asks to wait for longer than ``ImagePipeline/RetryPolicy/maximumDelay``, the request fails instead of keeping the task around for an image nobody is going to wait for.

## Retrying a Single Request

``ImageRequest/retryPolicy`` replaces the policy of the pipeline for a request. Use it to try harder for the images that matter, or to skip the retries for the ones that don't:

```swift
var hero = ImageRequest(url: heroURL)
hero.retryPolicy = ImagePipeline.RetryPolicy(maxRetryCount: 5)

var thumbnail = ImageRequest(url: thumbnailURL)
thumbnail.retryPolicy = .disabled
```

## Waiting for the Network

Retrying while the device is offline only spends the attempts, so a load that fails because of it waits for the device to get back online, for up to ``ImagePipeline/RetryPolicy/connectivityTimeout``, and then continues right away. If the time runs out, the load fails with the original error. A subway tunnel is the classic case: images fill in on their own at the next station.

Set the timeout to `0` to treat these failures the same way as the rest.

## Deciding in the Delegate

Implement ``ImagePipeline/Delegate-swift.protocol/retryDecision(for:pipeline:)`` for what a policy can't express. The method can suspend, so it can also fix what went wrong. Every attempt goes through ``ImagePipeline/Delegate-swift.protocol/willLoadData(for:urlRequest:pipeline:)``, so this is all it takes to refresh an expired token:

```swift
final class AuthenticatedPipelineDelegate: Sendable {}

extension AuthenticatedPipelineDelegate: ImagePipeline.Delegate {
func willLoadData(for request: ImageRequest, urlRequest: URLRequest, pipeline: ImagePipeline) async throws -> URLRequest {
var urlRequest = urlRequest
urlRequest.setValue("Bearer \(await TokenStore.shared.token)", forHTTPHeaderField: "Authorization")
return urlRequest
}

func retryDecision(for context: ImagePipeline.RetryContext, pipeline: ImagePipeline) async -> ImagePipeline.RetryDecision {
if context.statusCode == 401, context.retryCount == 0 {
await TokenStore.shared.refresh()
return .retry(after: 0)
}
return context.policy?.decision(for: context) ?? .stop
}
}
```

The last line falls back to the policy, which is what the default implementation does. The delegate has the last word, so ``ImagePipeline/RetryPolicy/maxRetryCount`` doesn't limit what it decides: check ``ImagePipeline/RetryContext/retryCount`` if it can return a retry for the same failure more than once.

> Tip: Throwing from `willLoadData` fails the request without asking about a retry. It's how the delegate says no.

## How Retries Fit into the Pipeline

A retry repeats the fetch of the data, and nothing around it, so the rest of the pipeline works the way it always does:

- **Coalescing.** Requests for the same image share the load, and with it the retries. Twenty cells with the same avatar make one sequence of requests, and the delegate is asked once per failed attempt. Requests can join while the load waits. If the requests have different policies, a failure is retried if any of them retries it, by the one that allows the most retries.
- **Queues.** A load that is waiting doesn't take up a slot in ``ImagePipeline/Configuration-swift.struct/dataLoadingQueue``, so a host that is down doesn't hold up the images from the hosts that work. Each attempt goes through the queue again, at the current priority.
- **Cancellation.** Cancelling a task stops the wait right away, unless other tasks are waiting for the same load.
- **Resumable downloads.** If the server supports it, a retry continues from where the failed attempt stopped. Otherwise, it starts over, and the progress goes back with it. See ``ImagePipeline/Configuration-swift.struct/isResumableDataEnabled``.
- **Prefetching.** ``ImagePrefetcher`` doesn't use the policy of the pipeline: prefetching is speculative, and it isn't worth the battery. Set a policy on the request to retry a prefetch. If a request for the image joins it, its policy applies.

## Observing Retries

``ImageTask/Status/retryCount`` says how many times the load started over while the task waited for it. With ``ImagePipeline/Configuration-swift.struct/isDiagnosticsEnabled`` on, ``ImageTask/Metrics`` has the rest: ``ImageTask/Metrics/retryCount``, the ``ImageTask/Metrics/Category/retry`` share of the time, and a download stage per attempt with the error it failed with.

```
j1 loadImage 478.2 ms
└─ j2 fetchOriginalImage 478.2 ms
├─ j3 fetchOriginalData 477.8 ms
│ ├─ dataLoadingQueue 1.5 ms
│ ├─ download 48.6 ms network · 0 bytes · HTTP 503 · dataLoadingFailed
│ ├─ retryDelay 426.6 ms
│ └─ download 0.4 ms network · 23 KB · HTTP 200 · first byte 0.3 ms
└─ decode 0.3 ms ImageDecoders.Default · jpeg 640×480
```

A task that is waiting to retry says so in ``ImagePipeline/Diagnostics-swift.struct/snapshot()``, and ``ImageTask/Metrics/summary`` ends with the number of retries. See <doc:troubleshooting>.

## Retrying on Request

Once the pipeline gives up, it's up to the person looking at the screen. All the views can repeat the last load:

```swift
LazyImage(url: url) { state in
if let image = state.image {
image.resizable().scaledToFill()
} else if state.error != nil {
Button("Try Again") { state.reload() }
} else {
ProgressView()
}
}
```

The same method is on `FetchImage`, `LazyImageView`, and `ImageLoader`.
2 changes: 2 additions & 0 deletions Documentation/Nuke.docc/Essentials/swiftui.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,8 @@ LazyImage(url: url) { state in
.clipped()
```

> Tip: To give people a way to try again, call `state.reload()`. To retry before showing an error, see <doc:retrying-requests>.

> Note: Unlike `AsyncImage`, `LazyImage` doesn't pass a phase enum to the closure – it passes the state itself, so you can read the download progress or the underlying ``ImageResponse`` while the view is on screen. See <doc:replacing-async-image> if you're moving from `AsyncImage`.

## Transitions
Expand Down
3 changes: 2 additions & 1 deletion Documentation/Nuke.docc/Essentials/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ The URLs in the lines have no query, which can carry a token. ``ImageTask/Metric
| `decoderNotRegistered` | The pipeline has a custom ``ImagePipeline/Configuration-swift.struct/makeImageDecoder`` that returned `nil` | Fall back to ``ImageDecoders/Default`` |
| `Response status code was unacceptable` | The server answered with an error | Check the URL. ``DataLoader`` rejects everything but `2xx` |
| `NSURLErrorDomain` and a code | `URLSession` failed. `-1009` is no connection, `-1004` is a refused connection, `-1022` is App Transport Security, and `-1001` is a timeout | See `URLError.Code` |
| `1 retry` at the end of the line | An attempt failed, and the ``ImagePipeline/RetryPolicy`` loaded the image again | Expected on a bad connection. ``ImageTask/Metrics`` has the error of every attempt |
| `dataMissingInCache` | The request has ``ImageRequest/Options-swift.struct/returnCacheDataDontLoad``, and the image isn't cached | Expected, unless you meant to load it |
| `cancelled` | The view went away, or something called `cancel()`. A cell that scrolls off the screen does it | Expected. To keep the download going when a `LazyImage` disappears, use `onDisappear(.lowerPriority)` |
| `success`, and the view is blank | The image loaded. The problem is in the view | `LazyImage(url:)` shows the image at its natural size. Check its frame, and call `resizable()` in the `content` closure |
Expand Down Expand Up @@ -66,7 +67,7 @@ From code, use ``ImagePipeline/Diagnostics-swift.struct/snapshot()``:
print(await ImagePipeline.shared.diagnostics.snapshot())
```

A queue at its limit with work pending means the pipeline is busy, and a task waits for a slot. A queue marked `suspended` starts nothing until ``TaskQueue/isSuspended`` is set back. A queue with free slots and a task that doesn't finish means the task is waiting on the server.
A queue at its limit with work pending means the pipeline is busy, and a task waits for a slot. A queue marked `suspended` starts nothing until ``TaskQueue/isSuspended`` is set back. A queue with free slots and a task that doesn't finish means the task is waiting on the server, unless the line of the task says `waiting to retry`: an attempt failed, and the pipeline is waiting for the delegate to decide on a retry, for the time to retry, or for the device to get back online. See <doc:retrying-requests>.

## Read the Whole Record

Expand Down
8 changes: 8 additions & 0 deletions Documentation/Nuke.docc/Extensions/ImagePipeline-Extension.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,14 @@ do {
- ``configuration-swift.property``
- ``Configuration-swift.struct``

### Retries

To learn more, see <doc:retrying-requests>.

- ``RetryPolicy``
- ``RetryDecision``
- ``RetryContext``

### Loading Images (Async/Await)

- ``image(for:)-(URL)``
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,12 @@ To learn more about caching, see <doc:caching>.
- ``ImagePipeline/DataCachePolicy``
- ``isStoringPreviewsInMemoryCache``

### Retries

To learn more, see <doc:retrying-requests>.

- ``retryPolicy``

### Other Options

- ``isDecompressionEnabled``
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@

- ``dataLoader(for:pipeline:)``
- ``willLoadData(for:urlRequest:pipeline:)``
- ``retryDecision(for:pipeline:)``

### Decoding and Encoding

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ let cachedRequest = ImageRequest(url: url, options: [.returnCacheDataDontLoad])
- ``scale``
- ``thumbnail``
- ``label``
- ``retryPolicy``
- ``userInfo``

### Nested Types
Expand Down
2 changes: 2 additions & 0 deletions Documentation/Nuke.docc/Nuke.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,10 @@ To install Nuke, use Swift Package Manager.

- <doc:image-processing>
- <doc:loading-data>
- <doc:retrying-requests>
- <doc:image-formats>
- ``ImagePipeline/Delegate-swift.protocol``
- ``ImagePipeline/RetryPolicy``
- ``AnimatedImageSource``
- ``AnimatedImageFrameDecoding``
- ``AnimatedImageFrameDecodingContext``
Expand Down
4 changes: 3 additions & 1 deletion Documentation/Nuke.docc/Performance/performance-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,9 @@ ImagePipeline.shared = ImagePipeline {

## Auto Retry

Enable [`waitsForConnectivity`](https://developer.apple.com/documentation/foundation/urlsessionconfiguration/2908812-waitsforconnectivity) on `URLSession` to indicate that the session should wait for connectivity to become available instead of failing the request immediately in case of a network failure.
Set ``ImagePipeline/Configuration-swift.struct/retryPolicy`` to retry the loads that fail for a reason that can go away, and to wait for the device to get back online. A load that is waiting doesn't take up a slot in the data loading queue. To learn more, see <doc:retrying-requests>.

Prefer it to [`waitsForConnectivity`](https://developer.apple.com/documentation/foundation/urlsessionconfiguration/2908812-waitsforconnectivity) on `URLSession`, which also waits for connectivity, but inside the request: it keeps the slot for as long as it waits, and the wait is limited by `timeoutIntervalForResource`, which is 7 days by default.

## Measure

Expand Down
2 changes: 2 additions & 0 deletions Documentation/Nuke.docc/Performance/prefetching.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,8 @@ To start prefetching, call ``ImagePrefetcher/startPrefetching(with:)-718dg`` met
- ``ImagePrefetcher/stopPrefetching(with:)-8cdam``
- ``ImagePrefetcher/stopPrefetching()``

A failed prefetch isn't retried, even if the pipeline has a ``ImagePipeline/Configuration-swift.struct/retryPolicy``, unless the request has one of its own: ``ImageRequest/retryPolicy``. A request for the same image that joins the prefetch brings its own retries.

The prefetcher automatically cancels all of the outstanding tasks when deallocated. All ``ImagePrefetcher`` methods are thread-safe and are optimized to be used even from the main thread during scrolling.

> Important: Prefetching takes up users' data and puts extra pressure on CPU and memory. To reduce the CPU and memory usage, you have an option to choose only the disk cache as a prefetching destination: ``ImagePrefetcher/Destination/diskCache``. It doesn't require image decoding and processing and therefore uses less CPU. The images are stored on disk, so they also take up less memory. This policy doesn't work with ``ImagePipeline/DataCachePolicy/storeEncodedImages`` cache policy and other policies that affect `loadData()`.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ struct ImageView: View {
- ``load(_:)-(URL?)``
- ``load(_:)-(ImageRequest?)``
- ``load(_:)-(()->ImageResponse)``
- ``reload()``
- ``cancel()``
- ``reset()``

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@

- ``url``
- ``request``
- ``reload()``
- ``cancel()``
- ``reset()``

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Load images from different sources and display them in your app using simple and

The framework is lean and has an automated test suite 2x the codebase size, ensuring excellent reliability. Nuke is optimized for [performance](https://kean-docs.github.io/nuke/documentation/nuke/performance-guide), and its advanced architecture enables virtually unlimited possibilities for customization.

> **Memory and Disk Cache** · **Image Processing & Decompression** · **Request Coalescing & Priority** · **Prefetching** · **Resumable Downloads** · **Progressive JPEG** · **HEIF, WebP, GIF** · **Animated Images** · **SwiftUI** · **Async/Await**
> **Memory and Disk Cache** · **Image Processing & Decompression** · **Request Coalescing & Priority** · **Prefetching** · **Resumable Downloads** · **Retries** · **Progressive JPEG** · **HEIF, WebP, GIF** · **Animated Images** · **SwiftUI** · **Async/Await**

## Sponsors

Expand Down
3 changes: 2 additions & 1 deletion Sources/Nuke/Diagnostics/DiagnosticsRecorder.swift
Original file line number Diff line number Diff line change
Expand Up @@ -216,7 +216,8 @@ extension ImagePipeline.Diagnostics {

private static func bytes(of jobs: [Job]) -> ImageTask.Metrics.Bytes? {
for job in jobs.reversed() {
for stage in job.stages where stage.kind == .download {
// The last attempt: it is the one that has the whole picture.
for stage in job.stages.reversed() where stage.kind == .download {
guard let bytes = stage.bytes else { continue }
return ImageTask.Metrics.Bytes(downloaded: bytes, resumed: stage.resumedBytes ?? 0, expected: stage.expectedBytes ?? bytes)
}
Expand Down
1 change: 1 addition & 0 deletions Sources/Nuke/Diagnostics/DiagnosticsSignposts.swift
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ extension ImagePipeline.Diagnostics.Stage.Kind {
case .diskLookup: "DiskLookup"
case .willLoadData: "WillLoadData"
case .download: "Download"
case .retryDelay: "RetryDelay"
case .diskStore: "DiskStore"
case .decode: "Decode"
case .process: "Process"
Expand Down
8 changes: 8 additions & 0 deletions Sources/Nuke/Diagnostics/ImagePipeline+Diagnostics.swift
Original file line number Diff line number Diff line change
Expand Up @@ -206,6 +206,10 @@ extension ImagePipeline.Diagnostics {
public internal(set) var expectedBytes: Int64?
/// The HTTP status code of a download.
public internal(set) var statusCode: Int?
/// The error a download failed with, which is the only record of it
/// for an attempt that was retried: ``Job/error`` is what the job
/// ended with.
public internal(set) var error: ErrorSummary?
/// When the first chunk of a download arrived, in seconds since 1970.
public internal(set) var firstByteAt: TimeInterval?
/// The `taskIdentifier` of the `URLSessionTask` that performed the
Expand Down Expand Up @@ -233,6 +237,10 @@ extension ImagePipeline.Diagnostics {
/// delegate returns.
case willLoadData
case download
/// The time between a failed download and the next attempt,
/// including the time the delegate took to decide on the retry.
/// There is one for every download the pipeline retries.
case retryDelay
case diskStore
case decode
case process
Expand Down
Loading
Loading