[kean]

Adds automatic retries, off by default, with one line to turn them on:

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

The default policy retries twice, about 0.5 s and 1 s apart, on transient URLErrors and on 408, 429, 500, 502, 503, and 504. It honors Retry-After, never repeats a request that isn't idempotent, and leaves Low Data Mode failures alone. A load that fails because the device is offline waits for it to get back online, for up to 30 s, instead of spending its attempts.

API

• ImagePipeline.RetryPolicy, set on Configuration.retryPolicy or ImageRequest.retryPolicy. .disabled opts a request out.
• Delegate.retryDecision(for:pipeline:) for what a policy can't express. It's async, and every attempt goes through willLoadData again, so it can refresh a token.
• ImageTask.Status.retryCount, plus ImageTask.Metrics.retryCount, per-attempt errors, a retryDelay stage, and a retry share of the time. summary and snapshot() report retries too, so a task that is waiting doesn't look stuck.
• reload() on FetchImage, LazyImageState, and LazyImageView, which replaces the .id(UUID()) recipe.

Why it's in the fetch and not in ImageTask

The retries run in the task that fetches the data (AsyncFetchTask, a new layer under the two fetch tasks). Coalesced tasks share one sequence, so twenty cells with the same avatar make one set of requests rather than twenty, and the delegate is asked once per failed attempt.

A task that is waiting gives its dataLoadingQueue slot back, so a dead host doesn't hold up the others. Each attempt goes through the rate limiter and the queue again, at the current priority, and resumes what the failed one downloaded.

The policy stays out of the task keys. On a failure, the job asks the requests waiting on it and uses the one that allows the most retries, so a prefetch and a request with a different policy still coalesce, and this costs nothing until something fails. ImagePrefetcher tasks skip the policy of the pipeline, because prefetching is speculative, but a request that joins one brings its own.

There's no new ImageTask.Event case, because Event is @frozen.

Proof

• .scripts/ci.sh: all 22 jobs pass on Xcode 27.1 RC, with Nuke at 1899 tests on iOS, 1896 on tvOS, and 1852 on macOS.
• The NukeTests scheme under TSan, the 32 tests in NukeThreadSafetyTests, and NukeVideo pass.
• 116 new tests in ImagePipelineRetryTests, RetryPolicyTests, and ConnectivityMonitorTests ran 40 times without a failure at a load average near 90, half of them under TSan.
• Breaking each of 11 safeguards on purpose failed a test: stale callbacks, the reset between attempts, the decoder reset, the prefetch exemption, the shared policy, cancelling the wait, and the rest.

Not checked: it hasn't been compiled on Xcode 26.x, which CI uses for the oldest macOS job, because the 26.6 install here has no swiftc.

Performance

Measured as instructions retired, with no retry policy, in a release harness over the public API, interleaved against main. The machine was at a load average of 60–100, so there are no wall-clock numbers.

	Change
ImageRequest creation	+0.25%	Real: 9 of 9 rounds, spread 0.04%, about 21 instructions for one more pointer
32-chunk download	−0.03%	Flat
Cancelled task	+0.21%	Flat
Memory cache hit	−0.99%	Flat
Load	+0.85%	21 rounds. An A/A control read +0.34%
Data load	+0.96%	21 rounds. An A/A control read −0.09%

The last two are small but aren't clearly noise, and nothing in the success path accounts for them. These numbers predate the rebase onto #1031. NukePerformanceTests needs a run on a quiet machine before this merges.

Before merging

• Stage.Kind.retryDelay and Metrics.Category.retry are new enum cases, so this is additive only if it lands before 14.0. After that, they would break exhaustive switches.
• Fix resumable downloads retrying a rejected range, progress on a resumed download without Content-Length, and empty local resources #1026 is still open. Without it, a custom policy that retries 416 repeats the rejected range. The default policy doesn't retry 416.
• The diagnostics schema goes to 3 for the new stage kind and Stage.error.
• A custom delegate with no policy adds one actor hop to every failure, because the delegate has to be asked. The default delegate stays synchronous.
• Not included: fallback URLs and the Low Data Mode fallback, which are separate items in the plan, and retrying decode failures, because the same bytes would fail again.
• No CHANGELOG entry yet.