Retry strategy

[tevelee]

Motivation

Add first-class retry support to the HTTP client so callers can express retry behavior in request options instead of building retry loops around each call. This is aimed at transient failures such as 503 Service Unavailable, 429 Too Many Requests, and selected transport errors, while also supporting standard Retry-After handling and request mutation between attempts.

Modifications

• Added a retry strategy capability to request options via HTTPClientCapability.RetryStrategy and HTTPRequestOptions.retryStrategy.
• Introduced the retry model types:
  • HTTPClientRetryStrategy
  • HTTPClientRetryAction
  • HTTPClientRetryContext
  • HTTPClientRequestBodyReplayability
  • HTTPClientRetryBackoff
• Added HTTPClientConditionalRetryStrategy for closure-based retry decisions and HTTPClientTransientFailureRetryStrategy for common transient failure handling.
• Added HTTPDateFormatter to parse and format RFC 9110 HTTP-date values used by Retry-After.
• Updated URLSessionHTTPClient to consult the retry strategy before exposing the response to the caller, retry requests with optional delay, and allow the retried request to be mutated.
• Extended the test HTTP server with retry-focused endpoints and added RetryStrategyTests covering backoff behavior, Retry-After handling, request mutation, and default retry rules for idempotent methods.

Result

HTTP client users can now attach retry policies directly to request options and get built-in retry handling for transient server responses and selected transport failures. The default transient failure strategy respects Retry-After, supports configurable backoff, and keeps non-idempotent methods such as POST non-retryable by default.

Test Plan

Added unit and integration coverage in RetryStrategyTests for:

• linear and exponential backoff calculation
• Retry-After seconds and HTTP-date parsing
• conditional retry request mutation
• transient failure retries with and without Retry-After
• non-retry behavior for POST by default

[FranzBusch]

Thank you for opening this PR. Before diving into the code details I would love to get @guoye-zhang and @fabianfett opinion on the general topic of retries. Is this something that we think a client should have request options for or users should build around a client with a more general purpose asynchronous retry method?

[guoye-zhang]

I think whatever retry API we design should align with fetch when it's finalized: whatwg/fetch#1838

It could be implemented in URLSession / AHC directly or as a middleware, but shouldn't be in the URLSessionHTTPClient conformance shim.

[fabianfett]

I think this is an explicit not yet. We are in the process of building agreement on the base API. Once we have that we can extend this with retries.