feat: support default API rate limiting policy with Polly (#46)

kamranayub · web-flow · commit 3d5a8bf8c292 · 2025-05-26T00:47:44.000-05:00
- Add new `IGDBClient.CreateWithDefaults` static helper to create an IGDB client configured with all the defaults
- Add default Polly API policy to `IGDB.ApiPolicy` static class and `DefaultApiPolicy` async policy
- Add an overload for passing an `IAsyncPolicy&lt;HttpResponseMessage&gt;` to the client constructor
diff --git a/.github/workflows/dotnet.yml b/.github/workflows/dotnet.yml
@@ -18,7 +18,7 @@ jobs:
       - name: Restore dependencies
         run: dotnet restore
       - name: Test
-        run: dotnet test --verbosity normal
+        run: dotnet test --verbosity normal --filter "Category!=SkipCi"
         env:
           IGDB_CLIENT_ID: ${{ secrets.IGDB_CLIENT_ID }}
           IGDB_CLIENT_SECRET: ${{ secrets.IGDB_CLIENT_SECRET }}
diff --git a/IGDB.Tests/AssemblyInfo.cs b/IGDB.Tests/AssemblyInfo.cs
@@ -0,0 +1,3 @@
+using Xunit;
+
+[assembly: CollectionBehavior(DisableTestParallelization = true)]
diff --git a/IGDB.Tests/Dumps.cs b/IGDB.Tests/Dumps.cs
@@ -7,19 +7,21 @@
 
 namespace IGDB.Tests
 {
+  [Collection("/dumps")]
   public class Dumps
   {
     IGDBClient _api;
 
     public Dumps()
     {
-      _api = new IGDB.IGDBClient(
+      _api = IGDBClient.CreateWithDefaults(
         Environment.GetEnvironmentVariable("IGDB_CLIENT_ID"),
         Environment.GetEnvironmentVariable("IGDB_CLIENT_SECRET")
       );
     }
 
     [Fact]
+    [Trait("Category", "SkipCi")]
     public async Task ShouldReturnDumpsList()
     {
       var dumps = await _api.GetDataDumpsAsync();
@@ -29,6 +31,7 @@ public async Task ShouldReturnDumpsList()
     }
 
     [Fact]
+    [Trait("Category", "SkipCi")]
     public async Task ShouldReturnGamesEndpointDump()
     {
       var gameDump = await _api.GetDataDumpEndpointAsync(IGDBClient.Endpoints.Games);
diff --git a/IGDB.Tests/GameTimeToBeats.cs b/IGDB.Tests/GameTimeToBeats.cs
@@ -4,13 +4,14 @@
 
 namespace IGDB.Tests
 {
+  [Collection("/game_time_to_beats")]
   public class GameTimeToBeats
   {
     IGDBClient _api;
 
     public GameTimeToBeats()
     {
-      _api = new IGDB.IGDBClient(
+      _api = IGDBClient.CreateWithDefaults(
         Environment.GetEnvironmentVariable("IGDB_CLIENT_ID"),
         Environment.GetEnvironmentVariable("IGDB_CLIENT_SECRET")
       );
diff --git a/IGDB.Tests/Games.cs b/IGDB.Tests/Games.cs
@@ -6,13 +6,14 @@
 
 namespace IGDB.Tests
 {
+  [Collection("/games")]
   public class Games
   {
     IGDBClient _api;
 
     public Games()
     {
-      _api = new IGDB.IGDBClient(
+      _api = IGDBClient.CreateWithDefaults(
         Environment.GetEnvironmentVariable("IGDB_CLIENT_ID"),
         Environment.GetEnvironmentVariable("IGDB_CLIENT_SECRET")
       );
diff --git a/IGDB.Tests/IGDB.Tests.csproj b/IGDB.Tests/IGDB.Tests.csproj
@@ -4,7 +4,6 @@
     <TargetFramework>net9.0</TargetFramework>
 
     <IsPackable>false</IsPackable>
-    <DefineConstants>$(DefineConstants);IGDB_TESTS</DefineConstants>
   </PropertyGroup>
 
   <ItemGroup>
diff --git a/IGDB.Tests/Platforms.cs b/IGDB.Tests/Platforms.cs
@@ -6,13 +6,14 @@
 
 namespace IGDB.Tests
 {
+  [Collection("/platforms")]
   public class Platforms
   {
     IGDBClient _api;
 
     public Platforms()
     {
-      _api = new IGDB.IGDBClient(
+      _api = IGDBClient.CreateWithDefaults(
         Environment.GetEnvironmentVariable("IGDB_CLIENT_ID"),
         Environment.GetEnvironmentVariable("IGDB_CLIENT_SECRET")
       );
diff --git a/IGDB.Tests/PopScore.cs b/IGDB.Tests/PopScore.cs
@@ -6,53 +6,54 @@
 
 namespace IGDB.Tests
 {
+  [Collection("/popularity_types")]
 	public class PopScore
-	{
-		IGDBClient _api;
+  {
+    IGDBClient _api;
 
-		public PopScore()
-		{
-			_api = new IGDB.IGDBClient(
-			  Environment.GetEnvironmentVariable("IGDB_CLIENT_ID"),
-			  Environment.GetEnvironmentVariable("IGDB_CLIENT_SECRET")
-			);
-		}
+    public PopScore()
+    {
+      _api = IGDBClient.CreateWithDefaults(
+        Environment.GetEnvironmentVariable("IGDB_CLIENT_ID"),
+        Environment.GetEnvironmentVariable("IGDB_CLIENT_SECRET")
+      );
+    }
 
-		[Fact]
-		public async Task ShouldReturnAllPopularityTypes()
-		{
-			var popularityTypes = await _api.QueryAsync<PopularityType>(IGDBClient.Endpoints.PopularityTypes, "fields *;");
+    [Fact]
+    public async Task ShouldReturnAllPopularityTypes()
+    {
+      var popularityTypes = await _api.QueryAsync<PopularityType>(IGDBClient.Endpoints.PopularityTypes, "fields *;");
 
-			Assert.NotNull(popularityTypes);
-			foreach (var popularityType in popularityTypes)
-			{
-				Assert.NotNull(popularityType.Checksum);
-				Assert.NotNull(popularityType.CreatedAt);
-				Assert.NotNull(popularityType.Name);
-				Assert.NotNull(popularityType.ExternalPopularitySource.Id);
-				Assert.NotNull(popularityType.UpdatedAt);
-			}
-		}
+      Assert.NotNull(popularityTypes);
+      foreach (var popularityType in popularityTypes)
+      {
+        Assert.NotNull(popularityType.Checksum);
+        Assert.NotNull(popularityType.CreatedAt);
+        Assert.NotNull(popularityType.Name);
+        Assert.NotNull(popularityType.ExternalPopularitySource.Id);
+        Assert.NotNull(popularityType.UpdatedAt);
+      }
+    }
 
-		[Fact]
-		public async Task ShouldReturnLimitedPopularityPrimitives()
-		{
-			var popularityPrimitives = await _api.QueryAsync<PopularityPrimitive>(
-				IGDBClient.Endpoints.PopularityPrimitives,
-				"fields *; limit 10;");
+    [Fact]
+    public async Task ShouldReturnLimitedPopularityPrimitives()
+    {
+      var popularityPrimitives = await _api.QueryAsync<PopularityPrimitive>(
+        IGDBClient.Endpoints.PopularityPrimitives,
+        "fields *; limit 10;");
 
-			Assert.NotNull(popularityPrimitives);
-			Assert.True(popularityPrimitives.Length == 10);
+      Assert.NotNull(popularityPrimitives);
+      Assert.True(popularityPrimitives.Length == 10);
 
-			foreach (var popularityPrimitive in popularityPrimitives)
-			{
-				Assert.NotNull(popularityPrimitive.CalculatedAt);
-				Assert.NotNull(popularityPrimitive.CreatedAt);
-				Assert.NotNull(popularityPrimitive.ExternalPopularitySource.Id);
-				Assert.NotNull(popularityPrimitive.PopularityType);
-				Assert.NotNull(popularityPrimitive.UpdatedAt);
-				Assert.NotNull(popularityPrimitive.Value);
-			}
-		}
-	}
+      foreach (var popularityPrimitive in popularityPrimitives)
+      {
+        Assert.NotNull(popularityPrimitive.CalculatedAt);
+        Assert.NotNull(popularityPrimitive.CreatedAt);
+        Assert.NotNull(popularityPrimitive.ExternalPopularitySource.Id);
+        Assert.NotNull(popularityPrimitive.PopularityType);
+        Assert.NotNull(popularityPrimitive.UpdatedAt);
+        Assert.NotNull(popularityPrimitive.Value);
+      }
+    }
+  }
 }
diff --git a/IGDB.Tests/TokenHandling.cs b/IGDB.Tests/TokenHandling.cs
@@ -18,7 +18,8 @@ public async Task ShouldHandleInvalidTokenAndRetryRequest()
       var invalidTokenClient = new IGDB.IGDBClient(
         Environment.GetEnvironmentVariable("IGDB_CLIENT_ID"),
         Environment.GetEnvironmentVariable("IGDB_CLIENT_SECRET"),
-        tokenStore
+        tokenStore,
+        ApiPolicy.DefaultApiPolicy
       );
 
       var games = await invalidTokenClient.QueryAsync<Game>("games");
@@ -34,7 +35,8 @@ public async Task ShouldHandleExpiredTokenAndAcquireNewOne()
       var client = new IGDB.IGDBClient(
         Environment.GetEnvironmentVariable("IGDB_CLIENT_ID"),
         Environment.GetEnvironmentVariable("IGDB_CLIENT_SECRET"),
-        tokenStore
+        tokenStore,
+        ApiPolicy.DefaultApiPolicy
       );
 
       await client.QueryAsync<Game>("games");
@@ -51,7 +53,8 @@ public async Task ShouldUseExistingTokenWhenNotExpired()
       var client = new IGDB.IGDBClient(
         Environment.GetEnvironmentVariable("IGDB_CLIENT_ID"),
         Environment.GetEnvironmentVariable("IGDB_CLIENT_SECRET"),
-        tokenStore
+        tokenStore,
+        ApiPolicy.DefaultApiPolicy
       );
 
       await client.QueryAsync<Game>("games");
diff --git a/IGDB/ApiPolicy.cs b/IGDB/ApiPolicy.cs
@@ -0,0 +1,50 @@
+using System;
+using System.Net.Http;
+using System.Threading.Tasks;
+using Polly;
+using Polly.Bulkhead;
+using Polly.RateLimit;
+
+namespace IGDB
+{
+  public static class ApiPolicy
+  {
+    private static readonly Random _jitter = new Random();
+    private const int MaxRetries = 3;
+    private const double RetryDelayBaseSeconds = 0.5;
+    private const int MaxParallelization = 6;
+    private const int MaxQueuingActions = 32;
+    private const int MaxRateLimit = 4;
+    private const int JitterMs = 500;
+    private static readonly TimeSpan RateLimitPeriod = TimeSpan.FromMilliseconds(900);
+
+    /// <summary>
+    /// Default API policy for handling HTTP requests to IGDB.
+    /// 
+    /// This policy includes:
+    /// - Retry logic for rate limit and bulkhead exceptions with exponential backoff and jitter.
+    /// - Bulkhead isolation to limit the number of concurrent requests.
+    /// - Rate limiting to control the request rate.
+    /// 
+    /// The retry logic will attempt to retry up to 3 times with an exponential backoff strategy,
+    /// adding a random jitter of up to ±500ms to avoid thundering herd problems.
+    /// </summary>
+    public static readonly IAsyncPolicy<HttpResponseMessage> DefaultApiPolicy
+        = Policy.WrapAsync(
+          Policy<HttpResponseMessage>.Handle<RateLimitRejectedException>()
+            .Or<BulkheadRejectedException>()
+            .WaitAndRetryAsync(
+              retryCount: MaxRetries,
+              sleepDurationProvider: (retryAttempt) =>
+              {
+                var backOff = TimeSpan.FromSeconds(RetryDelayBaseSeconds * Math.Pow(2, retryAttempt - 1));
+                var jitter = TimeSpan.FromMilliseconds(_jitter.Next(-JitterMs, JitterMs));
+                return backOff + jitter;
+              },
+              onRetry: (_, __, ___) => { }
+            ),
+            Policy.BulkheadAsync<HttpResponseMessage>(maxParallelization: MaxParallelization, maxQueuingActions: MaxQueuingActions),
+            Policy.RateLimitAsync<HttpResponseMessage>(MaxRateLimit, RateLimitPeriod)
+        );
+  }
+}
diff --git a/IGDB/IGDB.csproj b/IGDB/IGDB.csproj
@@ -31,6 +31,7 @@
   </PropertyGroup>
 
   <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Http.Polly" Version="9.0.5" />
     <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.0.0" PrivateAssets="All" />
   </ItemGroup>
 
diff --git a/IGDB/IGDBApi.cs b/IGDB/IGDBApi.cs
diff --git a/README.md b/README.md

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+using Xunit;`
	`2`	`+`
	`3`	`+[assembly: CollectionBehavior(DisableTestParallelization = true)]`
Original file line number	Diff line number	Diff line change
`@@ -7,19 +7,21 @@`
`7`	`7`
`8`	`8`	`namespace IGDB.Tests`
`9`	`9`	`{`
	`10`	`+ [Collection("/dumps")]`
`10`	`11`	`public class Dumps`
`11`	`12`	`{`
`12`	`13`	`IGDBClient _api;`
`13`	`14`
`14`	`15`	`public Dumps()`
`15`	`16`	`{`
`16`		`- _api = new IGDB.IGDBClient(`
	`17`	`+ _api = IGDBClient.CreateWithDefaults(`
`17`	`18`	`Environment.GetEnvironmentVariable("IGDB_CLIENT_ID"),`
`18`	`19`	`Environment.GetEnvironmentVariable("IGDB_CLIENT_SECRET")`
`19`	`20`	`);`
`20`	`21`	`}`
`21`	`22`
`22`	`23`	`[Fact]`
	`24`	`+ [Trait("Category", "SkipCi")]`
`23`	`25`	`public async Task ShouldReturnDumpsList()`
`24`	`26`	`{`
`25`	`27`	`var dumps = await _api.GetDataDumpsAsync();`
`@@ -29,6 +31,7 @@ public async Task ShouldReturnDumpsList()`
`29`	`31`	`}`
`30`	`32`
`31`	`33`	`[Fact]`
	`34`	`+ [Trait("Category", "SkipCi")]`
`32`	`35`	`public async Task ShouldReturnGamesEndpointDump()`
`33`	`36`	`{`
`34`	`37`	`var gameDump = await _api.GetDataDumpEndpointAsync(IGDBClient.Endpoints.Games);`
Original file line number	Diff line number	Diff line change
`@@ -4,13 +4,14 @@`
`4`	`4`
`5`	`5`	`namespace IGDB.Tests`
`6`	`6`	`{`
	`7`	`+ [Collection("/game_time_to_beats")]`
`7`	`8`	`public class GameTimeToBeats`
`8`	`9`	`{`
`9`	`10`	`IGDBClient _api;`
`10`	`11`
`11`	`12`	`public GameTimeToBeats()`
`12`	`13`	`{`
`13`		`- _api = new IGDB.IGDBClient(`
	`14`	`+ _api = IGDBClient.CreateWithDefaults(`
`14`	`15`	`Environment.GetEnvironmentVariable("IGDB_CLIENT_ID"),`
`15`	`16`	`Environment.GetEnvironmentVariable("IGDB_CLIENT_SECRET")`
`16`	`17`	`);`
Original file line number	Diff line number	Diff line change
`@@ -6,13 +6,14 @@`
`6`	`6`
`7`	`7`	`namespace IGDB.Tests`
`8`	`8`	`{`
	`9`	`+ [Collection("/games")]`
`9`	`10`	`public class Games`
`10`	`11`	`{`
`11`	`12`	`IGDBClient _api;`
`12`	`13`
`13`	`14`	`public Games()`
`14`	`15`	`{`
`15`		`- _api = new IGDB.IGDBClient(`
	`16`	`+ _api = IGDBClient.CreateWithDefaults(`
`16`	`17`	`Environment.GetEnvironmentVariable("IGDB_CLIENT_ID"),`
`17`	`18`	`Environment.GetEnvironmentVariable("IGDB_CLIENT_SECRET")`
`18`	`19`	`);`
Original file line number	Diff line number	Diff line change
`@@ -6,13 +6,14 @@`
`6`	`6`
`7`	`7`	`namespace IGDB.Tests`
`8`	`8`	`{`
	`9`	`+ [Collection("/platforms")]`
`9`	`10`	`public class Platforms`
`10`	`11`	`{`
`11`	`12`	`IGDBClient _api;`
`12`	`13`
`13`	`14`	`public Platforms()`
`14`	`15`	`{`
`15`		`- _api = new IGDB.IGDBClient(`
	`16`	`+ _api = IGDBClient.CreateWithDefaults(`
`16`	`17`	`Environment.GetEnvironmentVariable("IGDB_CLIENT_ID"),`
`17`	`18`	`Environment.GetEnvironmentVariable("IGDB_CLIENT_SECRET")`
`18`	`19`	`);`