feat(client): add retries support

Author: stainless-app[bot]

src/Orb/Core/ClientOptions.cs

@@ -21,6 +21,8 @@ public Uri BaseUrl
 
     public TimeSpan Timeout { get; set; } = TimeSpan.FromMinutes(1);
 
+    public int MaxRetries { get; set; } = 2;
+
     Lazy<string> _apiKey = new(() =>
         Environment.GetEnvironmentVariable("ORB_API_KEY")
         ?? throw new OrbInvalidDataException(

src/Orb/Core/HttpResponse.cs

@@ -32,6 +32,15 @@ await Message.Content.ReadAsStreamAsync(cts.Token).ConfigureAwait(false),
         }
     }
 
+    public async Task<string> ReadAsString(CancellationToken cancellationToken = default)
+    {
+        using var cts = CancellationTokenSource.CreateLinkedTokenSource(
+            this.CancellationToken,
+            cancellationToken
+        );
+        return await Message.Content.ReadAsStringAsync(cts.Token).ConfigureAwait(false);
+    }
+
     public void Dispose()
     {
         this.Message.Dispose();

src/Orb/IOrbClient.cs

@@ -32,6 +32,8 @@ public interface IOrbClient
 
     TimeSpan Timeout { get; init; }
 
+    int MaxRetries { get; init; }
+
     string APIKey { get; init; }
 
     string? WebhookSecret { get; init; }

src/Orb/OrbClient.cs

@@ -1,4 +1,8 @@
 using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Net;
 using System.Net.Http;
 using System.Threading;
 using System.Threading.Tasks;
@@ -25,6 +29,13 @@ namespace Orb;
 
 public sealed class OrbClient : IOrbClient
 {
+    static readonly ThreadLocal<Random> _threadLocalRandom = new(() => new Random());
+
+    static Random Random
+    {
+        get { return _threadLocalRandom.Value!; }
+    }
+
     readonly ClientOptions _options;
 
     public HttpClient HttpClient
@@ -51,6 +62,12 @@ public TimeSpan Timeout
         init { this._options.Timeout = value; }
     }
 
+    public int MaxRetries
+    {
+        get { return this._options.MaxRetries; }
+        init { this._options.MaxRetries = value; }
+    }
+
     public string APIKey
     {
         get { return this._options.APIKey; }
@@ -169,6 +186,63 @@ public async Task<HttpResponse> Execute<T>(
         CancellationToken cancellationToken = default
     )
         where T : ParamsBase
+    {
+        if (this.MaxRetries <= 0)
+        {
+            return await ExecuteOnce(request, cancellationToken).ConfigureAwait(false);
+        }
+
+        var retries = 0;
+        while (true)
+        {
+            HttpResponse? response = null;
+            try
+            {
+                response = await ExecuteOnce(request, cancellationToken).ConfigureAwait(false);
+            }
+            catch (Exception e)
+            {
+                if (++retries > this.MaxRetries || !ShouldRetry(e))
+                {
+                    throw;
+                }
+            }
+
+            if (response != null && (++retries > this.MaxRetries || !ShouldRetry(response)))
+            {
+                if (response.Message.IsSuccessStatusCode)
+                {
+                    return response;
+                }
+
+                try
+                {
+                    throw OrbExceptionFactory.CreateApiException(
+                        response.Message.StatusCode,
+                        await response.ReadAsString(cancellationToken).ConfigureAwait(false)
+                    );
+                }
+                catch (HttpRequestException e)
+                {
+                    throw new OrbIOException("I/O Exception", e);
+                }
+                finally
+                {
+                    response.Dispose();
+                }
+            }
+
+            var backoff = ComputeRetryBackoff(retries, response);
+            response?.Dispose();
+            await Task.Delay(backoff, cancellationToken).ConfigureAwait(false);
+        }
+    }
+
+    async Task<HttpResponse> ExecuteOnce<T>(
+        HttpRequest<T> request,
+        CancellationToken cancellationToken = default
+    )
+        where T : ParamsBase
     {
         using HttpRequestMessage requestMessage = new(request.Method, request.Params.Url(this))
         {
@@ -191,29 +265,100 @@ public async Task<HttpResponse> Execute<T>(
                 )
                 .ConfigureAwait(false);
         }
-        catch (HttpRequestException e1)
+        catch (HttpRequestException e)
         {
-            throw new OrbIOException("I/O exception", e1);
+            throw new OrbIOException("I/O exception", e);
         }
-        if (!responseMessage.IsSuccessStatusCode)
+        return new() { Message = responseMessage, CancellationToken = cts.Token };
+    }
+
+    static TimeSpan ComputeRetryBackoff(int retries, HttpResponse? response)
+    {
+        TimeSpan? apiBackoff = ParseRetryAfterMsHeader(response) ?? ParseRetryAfterHeader(response);
+        if (apiBackoff != null && apiBackoff < TimeSpan.FromMinutes(1))
         {
-            try
-            {
-                throw OrbExceptionFactory.CreateApiException(
-                    responseMessage.StatusCode,
-                    await responseMessage.Content.ReadAsStringAsync(cts.Token).ConfigureAwait(false)
-                );
-            }
-            catch (HttpRequestException e)
-            {
-                throw new OrbIOException("I/O Exception", e);
-            }
-            finally
-            {
-                responseMessage.Dispose();
-            }
+            // If the API asks us to wait a certain amount of time (and it's a reasonable amount), then just
+            // do what it says.
+            return (TimeSpan)apiBackoff;
         }
-        return new() { Message = responseMessage, CancellationToken = cts.Token };
+
+        // Apply exponential backoff, but not more than the max.
+        var backoffSeconds = Math.Min(0.5 * Math.Pow(2.0, retries - 1), 8.0);
+        var jitter = 1.0 - 0.25 * Random.NextDouble();
+        return TimeSpan.FromSeconds(backoffSeconds * jitter);
+    }
+
+    static TimeSpan? ParseRetryAfterMsHeader(HttpResponse? response)
+    {
+        IEnumerable<string>? headerValues = null;
+        response?.Message.Headers.TryGetValues("Retry-After-Ms", out headerValues);
+        var headerValue = headerValues == null ? null : Enumerable.FirstOrDefault(headerValues);
+        if (headerValue == null)
+        {
+            return null;
+        }
+
+        if (float.TryParse(headerValue.AsSpan(), out var retryAfterMs))
+        {
+            return TimeSpan.FromMilliseconds(retryAfterMs);
+        }
+
+        return null;
+    }
+
+    static TimeSpan? ParseRetryAfterHeader(HttpResponse? response)
+    {
+        IEnumerable<string>? headerValues = null;
+        response?.Message.Headers.TryGetValues("Retry-After", out headerValues);
+        var headerValue = headerValues == null ? null : Enumerable.FirstOrDefault(headerValues);
+        if (headerValue == null)
+        {
+            return null;
+        }
+
+        if (float.TryParse(headerValue.AsSpan(), out var retryAfterSeconds))
+        {
+            return TimeSpan.FromSeconds(retryAfterSeconds);
+        }
+        else if (DateTimeOffset.TryParse(headerValue.AsSpan(), out var retryAfterDate))
+        {
+            return retryAfterDate - DateTimeOffset.Now;
+        }
+
+        return null;
+    }
+
+    static bool ShouldRetry(HttpResponse response)
+    {
+        if (
+            response.Message.Headers.TryGetValues("X-Should-Retry", out var headerValues)
+            && bool.TryParse(Enumerable.FirstOrDefault(headerValues), out var shouldRetry)
+        )
+        {
+            // If the server explicitly says whether to retry, then we obey.
+            return shouldRetry;
+        }
+
+        return response.Message.StatusCode switch
+        {
+            // Retry on request timeouts
+            HttpStatusCode.RequestTimeout
+            or
+            // Retry on lock timeouts
+            HttpStatusCode.Conflict
+            or
+            // Retry on rate limits
+            HttpStatusCode.TooManyRequests
+            or
+            // Retry internal errors
+            >= HttpStatusCode.InternalServerError => true,
+            _ => false,
+        };
+    }
+
+    static bool ShouldRetry(Exception e)
+    {
+        return e is IOException || e is OrbIOException;
     }
 
     public OrbClient()