RetryableHttpErrorHandler Class

Namespace
Kampute.HttpClient.ErrorHandlers.Abstracts
Assembly
  • Kampute.HttpClient.dll

Definition

Provides the base class for error handlers that retry a request after a delay when it receives an error response with a transient status code.
public abstract class RetryableHttpErrorHandler : IHttpErrorHandler
Inheritance
  • object
  • RetryableHttpErrorHandler
Implements
Inherited by

Remarks

A derived class chooses the status codes it handles by overriding CanHandle(HttpStatusCode), and can change where the suggested retry time is read from and which policy applies when OnRetryPolicy provides none.

The handler decides how to retry when it handles the first error response of a call, and applies that decision to every later error response it handles during the same call:

By default, if the first error response suggests a retry time, for example in a Retry-After header, the request is retried once, at that time. If the retry receives another error response that this handler handles, the error reaches the caller, whatever retry time the new response suggests. If the first error response suggests no retry time, the policy of GetDefaultPolicy(HttpResponseErrorContext, Nullable<DateTimeOffset>) for that case applies to the rest of the call, and retry times suggested by later responses do not change its delays. Either way, a server cannot keep a call waiting by moving its suggested retry time further away.

Every suggested retry time is checked against MaxRetryDelay, which is five minutes by default. If a response suggests a time further away, the request is not retried, even when an earlier response of the same call was.

The handler counts only the retries it makes. Retries after connection failures, which HttpRestClient.RetryPolicy decides, and retries made by other handlers are counted separately, so a call that fails in several ways can be retried more times in total than any one of their limits allows.

Properties

MaxRetryDelay

Gets or sets the longest wait before a retry that this handler accepts when the server suggests a retry time.
public Nullable<TimeSpan> MaxRetryDelay { get; set; }

Property Value

Nullable<TimeSpan>
The longest accepted wait, or null to accept any suggested retry time. The default is five minutes.

Exceptions

ArgumentOutOfRangeException
Thrown if the value is negative.

Remarks

When a response suggests a retry time, for example in a Retry-After header, and that time is further away than this value, the handler does not retry the request, and the HttpResponseException for the response reaches the caller. The check applies to every response the handler handles, including later responses of a call that it has already retried. When the first error response of a call fails the check, OnRetryPolicy is not called.

This limit applies only to retry times suggested by the server. It does not limit the delays of a retry policy, such as the HttpRestClient.RetryPolicy used when the response suggests no retry time.

OnRetryPolicy

Gets or sets a function that chooses the retry policy of this handler for a call.
public Func<HttpResponseErrorContext, Nullable<DateTimeOffset>, IHttpRetryPolicy> OnRetryPolicy { get; set; }

Property Value

Func<HttpResponseErrorContext, Nullable<DateTimeOffset>, IHttpRetryPolicy>
A function that receives the context of the error response and the retry time the response suggests, and returns the IHttpRetryPolicy to use, or null to use the policy of GetDefaultPolicy(HttpResponseErrorContext, Nullable<DateTimeOffset>).

Remarks

The function is called once per call, for the first error response this handler handles. The policy it returns decides the retries of that response and of the later error responses this handler handles during the same call.

The function receives the following parameters:

Methods

CanHandle(HttpStatusCode)

Determines whether this handler can process the specified HTTP status code.
public abstract bool CanHandle(HttpStatusCode statusCode)

Parameters

statusCode HttpStatusCode
The HTTP status code to evaluate.

Returns

bool
true if the handler can process the status code; otherwise, false.

CreateSession(HttpResponseErrorContext)

Creates the retry session that decides the retries of this handler for a call.
protected virtual IRetrySession CreateSession(HttpResponseErrorContext ctx)

Parameters

ctx HttpResponseErrorContext
The context of the first error response this handler handles during the call.

Returns

IRetrySession
An IRetrySession that decides on the retry attempts, or null if the request must not be retried.

Exceptions

ArgumentNullException
Thrown if ctx is null.

Remarks

The handler calls this method only for the first error response it handles during a call. The later error responses it handles during the same call reuse the session this method returns.

If the response suggests a retry time further away than MaxRetryDelay, the method returns null, so the request is not retried. Otherwise, it creates the session from the policy that OnRetryPolicy returns, or from the policy of GetDefaultPolicy(HttpResponseErrorContext, Nullable<DateTimeOffset>).

GetDefaultPolicy(HttpResponseErrorContext, Nullable<DateTimeOffset>)

Returns the retry policy of this handler for a call when OnRetryPolicy provides none.
protected virtual IHttpRetryPolicy GetDefaultPolicy(HttpResponseErrorContext ctx, Nullable<DateTimeOffset> retryTime)

Parameters

ctx HttpResponseErrorContext
The context of the first error response this handler handles during the call.
retryTime Nullable<DateTimeOffset>
The retry time the response suggests, or null if it suggests none.

Returns

IHttpRetryPolicy
The base implementation returns a policy that retries once, at retryTime, if the response suggests a retry time, and the HttpRestClient.RetryPolicy of the client otherwise.

Exceptions

ArgumentNullException
Thrown if ctx is null.

GetSuggestedRetryTime(HttpResponseErrorContext)

Reads the retry time that an error response suggests.
protected virtual Nullable<DateTimeOffset> GetSuggestedRetryTime(HttpResponseErrorContext ctx)

Parameters

ctx HttpResponseErrorContext
The context containing information about the HTTP response.

Returns

Nullable<DateTimeOffset>
The time the response suggests for the retry, or null if it suggests none. The base implementation reads the Retry-After header.

Exceptions

ArgumentNullException
Thrown if ctx is null.

Explicit Interface Implementations

IHttpErrorHandler.DecideOnRetryAsync(HttpResponseErrorContext, CancellationToken)

Decides whether to retry a request after an error response.
Task<HttpErrorHandlerResult> IHttpErrorHandler.DecideOnRetryAsync(HttpResponseErrorContext ctx, CancellationToken cancellationToken)

Parameters

ctx HttpResponseErrorContext
The context containing information about the HTTP response that indicates a failure.
cancellationToken CancellationToken
A token for canceling the operation.

Returns

Task<HttpErrorHandlerResult>
A task that resolves to HttpErrorHandlerResult.Retry(HttpRequestMessage) with the request to send, or to HttpErrorHandlerResult.NoRetry to let the next handler decide.

Exceptions

ArgumentNullException
Thrown if ctx is null.

See Also