HttpError401Handler Class

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

Definition

Handles '401 Unauthorized' HTTP responses by attempting to re-authenticate and retry the request.
public class HttpError401Handler : IHttpErrorHandler, IDisposable
Inheritance
Implements

Remarks

The HttpError401Handler class is specifically designed to enhance instances of HttpRestClient by providing a mechanism to handle HTTP '401 Unauthorized' responses. When a request made by a HttpRestClient instance receives a '401 Unauthorized' status code, this indicates that the request was rejected due to insufficient or missing authentication credentials. The HttpError401Handler responds to such scenarios by initiating a re-authentication process using a delegate provided at instantiation, to obtain new authentication credentials.

The delegate provided to the constructor is tasked with obtaining new authentication credentials, which might involve interacting with an authentication server or prompting the user for credentials. Successful acquisition of new credentials leads to their application to the HttpRestClient instance, allowing the previously failed request to be retried with the updated authentication details.

When an authentication process is underway for a client, subsequent authentication requests from the client will not initiate new processes. Instead, they will await and utilize the outcome of the ongoing authentication. This approach guarantees that the authentication delegate is executed a single time for concurrent requests, ensuring both efficiency and thread safety.

A single instance of this error handler can be shared with multiple HttpRestClient instances, enabling centralized management of authentication challenges across various client instances that interact with different endpoints, if the HttpRestClient instances share the same authentication details. This enables a more efficient use of credentials and reduces the need for frequent re-authentications.

Constructors

HttpError401Handler(Func<HttpResponseErrorContext, CancellationToken, Task<AuthenticationHeaderValue>>)

Initializes a new instance of the HttpError401Handler class.
public HttpError401Handler(Func<HttpResponseErrorContext, CancellationToken, Task<AuthenticationHeaderValue>> asyncAuthenticator)

Parameters

asyncAuthenticator Func<HttpResponseErrorContext, CancellationToken, Task<AuthenticationHeaderValue>>
The asynchronous delegate to be invoked to acquire new authorization details. The delegate receives the following parameters:
  • context– Provides context about the HTTP response indicating a '401 Unauthorized' error. It is encapsulated within an HttpResponseErrorContext instance, allowing for an informed decision on authentication.
  • cancellationToken– A CancellationToken for canceling the operation.
The delegate should return a task resolving to an instance of AuthenticationHeaderValue containing the authorization details necessary for subsequent requests if authentication can be successfully completed. If the authentication process fails, the delegate should return null.

Exceptions

ArgumentNullException
Thrown if asyncAuthenticator is null.

Methods

AuthenticateAsync(HttpResponseErrorContext, CancellationToken)

Asynchronously authenticates an HTTP request that resulted in a '401 Unauthorized' response.
protected virtual Task<AuthenticationHeaderValue> AuthenticateAsync(HttpResponseErrorContext ctx, CancellationToken cancellationToken)

Parameters

ctx HttpResponseErrorContext
The error context for the HTTP response.
cancellationToken CancellationToken
A token for canceling the operation.

Returns

Task<AuthenticationHeaderValue>
A task that resolves to an AuthenticationHeaderValue if the client successfully acquires new authorization details; otherwise, null.

Exceptions

ArgumentNullException
Throws if ctx is null.

CanHandle(HttpStatusCode)

Determines whether this handler can process the specified HTTP status code.
public 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.

Remarks

This implementation specifically handles the HTTP '401 Unauthorized' status code.

Dispose()

Releases the unmanaged resources used by the HttpError401Handler and optionally disposes of the managed resources.
public void Dispose()

Explicit Interface Implementations

IHttpErrorHandler.DecideOnRetryAsync(HttpResponseErrorContext, CancellationToken)

Evaluates whether a failed request should be retried based on the error context.
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 an HttpErrorHandlerResult.

Exceptions

ArgumentNullException
Thrown if ctx is null.

See Also