Implement secondary rate limit handling in GitHub CLI

Co-authored-by: begonaguereca <[email protected]>

Author: Copilot

RELEASENOTES.md

@@ -1 +1,4 @@
+# Release Notes
 
+## What's New
+- Added secondary rate limit handling to GitHub CLI commands to gracefully handle 403/429 responses with proper retry logic, exponential backoff, and clear error messaging. This improves reliability when running multiple concurrent migrations.

src/Octoshift/Services/GithubClient.cs

@@ -22,6 +22,8 @@ public class GithubClient
 
     private const string DEFAULT_RATE_LIMIT_REMAINING = "5000";
     private const int MILLISECONDS_PER_SECOND = 1000;
+    private const int SECONDARY_RATE_LIMIT_MAX_RETRIES = 3;
+    private const int SECONDARY_RATE_LIMIT_DEFAULT_DELAY = 60; // 60 seconds default delay
 
     public GithubClient(OctoLogger log, HttpClient httpClient, IVersionProvider versionProvider, RetryPolicy retryPolicy, DateTimeProvider dateTimeProvider, string personalAccessToken)
     {
@@ -159,7 +161,8 @@ public virtual async Task<string> PatchAsync(string url, object body, Dictionary
         string url,
         object body = null,
         HttpStatusCode expectedStatus = HttpStatusCode.OK,
-        Dictionary<string, string> customHeaders = null)
+        Dictionary<string, string> customHeaders = null,
+        int retryCount = 0)
     {
         await ApplyRetryDelayAsync();
         _log.LogVerbose($"HTTP {httpMethod}: {url}");
@@ -199,9 +202,15 @@ public virtual async Task<string> PatchAsync(string url, object body, Dictionary
             SetRetryDelay(headers);
         }
 
+        // Check for secondary rate limits before handling primary rate limits
+        if (IsSecondaryRateLimit(response.StatusCode, content))
+        {
+            return await HandleSecondaryRateLimit(httpMethod, url, body, expectedStatus, customHeaders, response, content, headers, retryCount);
+        }
+
         if (response.StatusCode == HttpStatusCode.Forbidden && _retryDelay > 0)
         {
-            (content, headers) = await SendAsync(httpMethod, url, body, expectedStatus, customHeaders);
+            (content, headers) = await SendAsync(httpMethod, url, body, expectedStatus, customHeaders, retryCount);
         }
         else if (expectedStatus == HttpStatusCode.OK)
         {
@@ -280,4 +289,78 @@ private void EnsureSuccessGraphQLResponse(JObject response)
             throw new OctoshiftCliException($"{errorMessage ?? "UNKNOWN"}");
         }
     }
+
+    private bool IsSecondaryRateLimit(HttpStatusCode statusCode, string content)
+    {
+        // Secondary rate limits return 403 or 429
+        if (statusCode is not HttpStatusCode.Forbidden and not HttpStatusCode.TooManyRequests)
+        {
+            return false;
+        }
+
+        // Check if this is a primary rate limit (which we handle separately)
+        if (content.ToUpper().Contains("API RATE LIMIT EXCEEDED"))
+        {
+            return false;
+        }
+
+        // Common secondary rate limit error patterns
+        var contentUpper = content.ToUpper();
+        return contentUpper.Contains("SECONDARY RATE LIMIT") ||
+               contentUpper.Contains("ABUSE DETECTION") ||
+               contentUpper.Contains("YOU HAVE TRIGGERED AN ABUSE DETECTION MECHANISM") ||
+               statusCode == HttpStatusCode.TooManyRequests;
+    }
+
+    private async Task<(string Content, KeyValuePair<string, IEnumerable<string>>[] ResponseHeaders)> HandleSecondaryRateLimit(
+        HttpMethod httpMethod,
+        string url,
+        object body,
+        HttpStatusCode expectedStatus,
+        Dictionary<string, string> customHeaders,
+        HttpResponseMessage response,
+        string content,
+        KeyValuePair<string, IEnumerable<string>>[] headers,
+        int retryCount = 0)
+    {
+        if (retryCount >= SECONDARY_RATE_LIMIT_MAX_RETRIES)
+        {
+            throw new OctoshiftCliException($"Secondary rate limit exceeded. Maximum retries ({SECONDARY_RATE_LIMIT_MAX_RETRIES}) reached. Please wait before retrying your request.");
+        }
+
+        var delaySeconds = GetSecondaryRateLimitDelay(headers, retryCount);
+
+        _log.LogWarning($"Secondary rate limit detected (attempt {retryCount + 1}/{SECONDARY_RATE_LIMIT_MAX_RETRIES}). Waiting {delaySeconds} seconds before retrying...");
+
+        await Task.Delay(delaySeconds * MILLISECONDS_PER_SECOND);
+
+        return await SendAsync(httpMethod, url, body, expectedStatus, customHeaders, retryCount + 1);
+    }
+
+    private int GetSecondaryRateLimitDelay(KeyValuePair<string, IEnumerable<string>>[] headers, int retryCount)
+    {
+        // First check for retry-after header
+        var retryAfterHeader = ExtractHeaderValue("Retry-After", headers);
+        if (!string.IsNullOrEmpty(retryAfterHeader) && int.TryParse(retryAfterHeader, out var retryAfterSeconds))
+        {
+            return retryAfterSeconds;
+        }
+
+        // Then check if x-ratelimit-remaining is 0 and use x-ratelimit-reset
+        var rateLimitRemaining = GetRateLimitRemaining(headers);
+        if (rateLimitRemaining <= 0)
+        {
+            var resetUnixSeconds = GetRateLimitReset(headers);
+            var currentUnixSeconds = _dateTimeProvider.CurrentUnixTimeSeconds();
+            var delayFromReset = (int)(resetUnixSeconds - currentUnixSeconds);
+
+            if (delayFromReset > 0)
+            {
+                return delayFromReset;
+            }
+        }
+
+        // Otherwise use exponential backoff: 1m → 2m → 4m
+        return SECONDARY_RATE_LIMIT_DEFAULT_DELAY * (int)Math.Pow(2, retryCount);
+    }
 }

src/OctoshiftCLI.Tests/Octoshift/Services/GithubClientTests.cs

@@ -2084,6 +2084,34 @@ public void It_Only_Sets_The_Product_Name_In_User_Agent_Header_When_Version_Prov
         httpClient.DefaultRequestHeaders.UserAgent.ToString().Should().Be("OctoshiftCLI");
     }
 
+    [Fact]
+    public async Task PostAsync_Handles_Secondary_Rate_Limit_With_429_Status()
+    {
+        // Arrange
+        var handlerMock = new Mock<HttpMessageHandler>();
+        handlerMock
+            .Protected()
+            .SetupSequence<Task<HttpResponseMessage>>(
+                "SendAsync",
+                ItExpr.Is<HttpRequestMessage>(req => req.Method == HttpMethod.Post),
+                ItExpr.IsAny<CancellationToken>())
+            .ReturnsAsync(CreateHttpResponseFactory(
+                statusCode: HttpStatusCode.TooManyRequests,
+                content: "Too many requests",
+                headers: new[] { ("Retry-After", "1") })())
+            .ReturnsAsync(CreateHttpResponseFactory(content: "SUCCESS_RESPONSE")());
+
+        using var httpClient = new HttpClient(handlerMock.Object);
+        var githubClient = new GithubClient(_mockOctoLogger.Object, httpClient, null, _retryPolicy, _dateTimeProvider.Object, PERSONAL_ACCESS_TOKEN);
+
+        // Act
+        var result = await githubClient.PostAsync("http://example.com", _rawRequestBody);
+
+        // Assert
+        result.Should().Be("SUCCESS_RESPONSE");
+        _mockOctoLogger.Verify(m => m.LogWarning(It.Is<string>(s => s.Contains("Secondary rate limit detected"))), Times.Once);
+    }
+
     private object CreateRepositoryMigration(string migrationId = null, string state = RepositoryMigrationStatus.Succeeded) => new
     {
         id = migrationId ?? Guid.NewGuid().ToString(),