TimeoutHandler for smarter timeout handling with HttpClient

0. README.md

TimeoutHandler for smarter timeout handling with HttpClient

This code illustrates the blog article Better timeout handling with HttpClient.

Key features:

• control the timeout per request, rather than globally for all requests
• throw a more sensible exception (TimeoutException) when a timeout occurs, instead of the usual OperationCanceledException

1. HttpRequestExtensions.cs

public static class HttpRequestExtensions
{
    private const string TimeoutPropertyKey = "RequestTimeout";
    
    public static void SetTimeout(this HttpRequestMessage request, TimeSpan? timeout)
    {
        if (request == null) throw new ArgumentNullException(nameof(request));
        request.Properties[TimeoutPropertyKey] = timeout;
    }
    
    public static TimeSpan? GetTimeout(this HttpRequestMessage request)
    {
        if (request == null) throw new ArgumentNullException(nameof(request));
        if (request.Properties.TryGetValue(TimeoutPropertyKey, out var value) && value is TimeSpan timeout)
            return timeout;
        return null;
    }
}

2. TimeoutHandler.cs

public class TimeoutHandler : DelegatingHandler
{
    public TimeSpan DefaultTimeout { get; set; } = TimeSpan.FromSeconds(100);
    
    protected async override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        using (var cts = GetCancellationTokenSource(request, cancellationToken))
        {
            try
            {
                return await base.SendAsync(request, cts?.Token ?? cancellationToken);
            }
            catch(OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
            {
                throw new TimeoutException();
            }
        }
    }
    
    private CancellationTokenSource GetCancellationTokenSource(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        var timeout = request.GetTimeout() ?? DefaultTimeout;
        if (timeout == Timeout.InfiniteTimeSpan)
        {
            // No need to create a CTS if there's no timeout
            return null;
        }
        else
        {
            var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
            cts.CancelAfter(timeout);
            return cts;
        }
    }
}

3. Test.cs

async Task TestAsync()
{
    var handler = new TimeoutHandler
    {
        DefaultTimeout = TimeSpan.FromSeconds(10),
        InnerHandler = new HttpClientHandler()
    };

    using (var cts = new CancellationTokenSource())
    using (var client = new HttpClient(handler))
    {
        client.Timeout = Timeout.InfiniteTimeSpan;
        
        var request = new HttpRequestMessage(HttpMethod.Get, "http://localhost:8888/");

        // Uncomment to test per-request timeout
        //request.SetTimeout(TimeSpan.FromSeconds(5));
        
        // Uncomment to test that cancellation still works properly
        //cts.CancelAfter(TimeSpan.FromSeconds(2));
        
        using (var response = await client.SendAsync(request, cts.Token))
        {
            Console.WriteLine(response.StatusCode);
        }
    }
}

Why not just subclass the derived class at that point then?

That couples the timeout functionality to the other property that the subclass implemented, which may not be desirable. Alternatively, I may not even be able to subclass it if it came from a third-party library that sealed it. But any subclass of HttpRequestMessage will have the property bag.

Why not just subclass the derived class at that point then?

That couples the timeout functionality to the other property that the subclass implemented, which may not be desirable. Alternatively, I may not even be able to subclass it if it came from a third-party library that sealed it. But any subclass of HttpRequestMessage will have the property bag.

Yes, but if you’re debating use cases here then there’s also a case to be made for the mutability of the data in that dictionary being undesirable as well. If that was the case with a third party lib then it might also be the case that they hide that property to avoid external fiddling as well anyways. Thus, third party libs can introduce problems with your ability to access and use the internal dictionary just as equally as it can affect your ability to inherit from a class... There’s no guarantee that you’d have access to these things with a third party lib depending on the functionality it provides (i.e. Open-closed principle might hide this property but expose other things for extensibility). As such, I think this discussion should omit the unknown.

This is a lifesaver. I did have to tweak it to work on a mobile client. The error thrown is InvalidOperationException. Also, .net8.0 has obsoleted request.Properties, so I modified it to use request.Options. Other than that, it works great and I only have to change the timeout in the few places where I need to wait a little longer.