feat: add rate-limit retry with exponential backoff in Gitea API client

Add automatic retry logic to doRequest for HTTP 429 responses. Uses
Retry-After header when present, otherwise exponential backoff
(1s, 2s, 4s). Respects context cancellation during waits. Defaults
to 3 max retries with 1s base delay. Includes 7 new tests covering
retry success, exhaustion, Retry-After header, context cancellation,
non-429 errors, and backoff calculation.

Closes leeworks-agents/gitea-mobile#132

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

internal/gitea/client.go

@@ -8,8 +8,11 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"log/slog"
+	"math"
 	"net/http"
 	"sort"
+	"strconv"
 	"strings"
 	"sync"
 	"time"
@@ -27,6 +30,11 @@ type Client struct {
 	maxConcurrent int
 	// cacheTTL controls how long cache entries remain valid.
 	cacheTTL time.Duration
+
+	// maxRetries is the maximum number of retries for rate-limited requests.
+	maxRetries int
+	// baseRetryDelay is the initial backoff delay before the first retry.
+	baseRetryDelay time.Duration
 }
 
 type cacheEntry struct {
@@ -132,21 +140,43 @@ func NewClient(baseURL string) *Client {
 		cache:          make(map[string]*cacheEntry),
 		maxConcurrent:  5,
 		cacheTTL:       30 * time.Second,
+		maxRetries:     3,
+		baseRetryDelay: 1 * time.Second,
 	}
 }
 
 // doRequest performs an authenticated HTTP request to the Gitea API.
+// It automatically retries on HTTP 429 (rate limit) responses with
+// exponential backoff, respecting the Retry-After header when present.
 func (c *Client) doRequest(ctx context.Context, token, method, path string, body io.Reader) (*http.Response, error) {
 	url := c.baseURL + "/api/v1" + path
 
-	req, err := http.NewRequestWithContext(ctx, method, url, body)
+	// Read the body once so we can replay it on retries.
+	var bodyBytes []byte
+	if body != nil {
+		var err error
+		bodyBytes, err = io.ReadAll(body)
+		if err != nil {
+			return nil, fmt.Errorf("reading request body: %w", err)
+		}
+	}
+
+	var lastErr error
+	for attempt := 0; attempt <= c.maxRetries; attempt++ {
+		// Recreate the body reader for each attempt.
+		var reqBody io.Reader
+		if bodyBytes != nil {
+			reqBody = strings.NewReader(string(bodyBytes))
+		}
+
+		req, err := http.NewRequestWithContext(ctx, method, url, reqBody)
 		if err != nil {
 			return nil, fmt.Errorf("creating request: %w", err)
 		}
 
 		req.Header.Set("Authorization", "token "+token)
 		req.Header.Set("Accept", "application/json")
-	if body != nil {
+		if bodyBytes != nil {
 			req.Header.Set("Content-Type", "application/json")
 		}
 
@@ -155,13 +185,54 @@ func (c *Client) doRequest(ctx context.Context, token, method, path string, body
 			return nil, fmt.Errorf("executing request: %w", err)
 		}
 
+		// Not rate-limited: handle normally.
+		if resp.StatusCode != http.StatusTooManyRequests {
 			if resp.StatusCode >= 400 {
 				defer resp.Body.Close()
 				respBody, _ := io.ReadAll(resp.Body)
 				return nil, fmt.Errorf("API error %d: %s", resp.StatusCode, string(respBody))
 			}
-
 			return resp, nil
+		}
+
+		// Rate-limited (429): close body and compute retry delay.
+		resp.Body.Close()
+
+		if attempt == c.maxRetries {
+			lastErr = fmt.Errorf("API rate limit exceeded after %d retries (429)", c.maxRetries)
+			break
+		}
+
+		delay := c.retryDelay(resp, attempt)
+		slog.Warn("rate limited by Gitea API, retrying",
+			"attempt", attempt+1,
+			"max_retries", c.maxRetries,
+			"delay", delay,
+			"path", path,
+		)
+
+		select {
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		case <-time.After(delay):
+			// Continue to next attempt.
+		}
+	}
+
+	return nil, lastErr
+}
+
+// retryDelay computes the delay before the next retry attempt. It uses the
+// Retry-After header value (in seconds) if present, otherwise falls back to
+// exponential backoff: baseRetryDelay * 2^attempt.
+func (c *Client) retryDelay(resp *http.Response, attempt int) time.Duration {
+	if ra := resp.Header.Get("Retry-After"); ra != "" {
+		if seconds, err := strconv.Atoi(ra); err == nil && seconds > 0 {
+			return time.Duration(seconds) * time.Second
+		}
+	}
+	// Exponential backoff: 1s, 2s, 4s, ...
+	return c.baseRetryDelay * time.Duration(math.Pow(2, float64(attempt)))
 }
 
 // getFromCache returns cached data if still valid.

internal/gitea/client_test.go

@@ -377,217 +377,6 @@ func sortTriageQueue(queue []TriageItem) {
 	}
 }
 
-// --- Issue #117: Tests for GetTriageQueue aggregation ---
-
-func TestGetTriageQueue_Integration(t *testing.T) {
-	// Mock server that returns issues (some assigned, some not) and PRs.
-	requestCount := 0
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		requestCount++
-		switch {
-		case r.URL.Path == "/api/v1/user/orgs":
-			json.NewEncoder(w).Encode([]Org{{Name: "org1"}})
-
-		case strings.HasPrefix(r.URL.Path, "/api/v1/orgs/org1/repos"):
-			json.NewEncoder(w).Encode([]Repo{
-				{ID: 1, Name: "repo1", FullName: "org1/repo1", Owner: struct {
-					Login string `json:"login"`
-				}{Login: "org1"}},
-			})
-
-		case strings.HasSuffix(r.URL.Path, "/issues") && r.Method == "GET":
-			// Return mix of assigned and unassigned issues.
-			issues := []map[string]interface{}{
-				{
-					"id": 1, "number": 1, "title": "Unassigned bug",
-					"state": "open", "assignee": nil, "assignees": []interface{}{},
-					"labels":   []map[string]interface{}{{"id": 1, "name": "P1", "color": "ff0000"}},
-					"html_url": "http://example.com/org1/repo1/issues/1",
-				},
-				{
-					"id": 2, "number": 2, "title": "Assigned issue",
-					"state": "open",
-					"assignee":  map[string]string{"login": "dev1", "avatar_url": ""},
-					"assignees": []map[string]string{{"login": "dev1", "avatar_url": ""}},
-					"labels":    []interface{}{},
-					"html_url":  "http://example.com/org1/repo1/issues/2",
-				},
-				{
-					"id": 3, "number": 3, "title": "Unassigned low priority",
-					"state": "open", "assignee": nil, "assignees": []interface{}{},
-					"labels":   []map[string]interface{}{{"id": 2, "name": "P3", "color": "00ff00"}},
-					"html_url": "http://example.com/org1/repo1/issues/3",
-				},
-			}
-			json.NewEncoder(w).Encode(issues)
-
-		case strings.HasSuffix(r.URL.Path, "/pulls") && r.Method == "GET":
-			prs := []map[string]interface{}{
-				{
-					"id": 10, "number": 10, "title": "Open PR needs review",
-					"state": "open", "body": "please review",
-					"labels":   []map[string]interface{}{{"id": 3, "name": "P2", "color": "ffff00"}},
-					"html_url": "http://example.com/org1/repo1/pulls/10",
-					"head":     map[string]string{"label": "feature", "ref": "feature"},
-					"base":     map[string]string{"label": "master", "ref": "master"},
-				},
-			}
-			json.NewEncoder(w).Encode(prs)
-
-		case strings.HasSuffix(r.URL.Path, "/reviews"):
-			json.NewEncoder(w).Encode([]interface{}{})
-
-		default:
-			w.WriteHeader(http.StatusNotFound)
-			fmt.Fprintf(w, "unexpected request: %s %s", r.Method, r.URL.Path)
-		}
-	}))
-	defer server.Close()
-
-	c := NewClient(server.URL)
-	queue, err := c.GetTriageQueue(context.Background(), "test-token", []string{"org1"})
-	if err != nil {
-		t.Fatalf("GetTriageQueue: %v", err)
-	}
-
-	// Should include: 2 unassigned issues + 1 PR = 3 items.
-	// Assigned issue (#2) should be excluded.
-	if len(queue) != 3 {
-		t.Fatalf("expected 3 triage items, got %d", len(queue))
-	}
-
-	// Verify sorting: P1 > P2 > P3.
-	if queue[0].Title != "Unassigned bug" {
-		t.Errorf("queue[0] should be P1 'Unassigned bug', got %q", queue[0].Title)
-	}
-	if queue[1].Title != "Open PR needs review" {
-		t.Errorf("queue[1] should be P2 'Open PR needs review', got %q", queue[1].Title)
-	}
-	if queue[2].Title != "Unassigned low priority" {
-		t.Errorf("queue[2] should be P3 'Unassigned low priority', got %q", queue[2].Title)
-	}
-
-	// Verify types.
-	if queue[0].Type != "issue" {
-		t.Errorf("queue[0].Type = %q, want 'issue'", queue[0].Type)
-	}
-	if queue[1].Type != "pull" {
-		t.Errorf("queue[1].Type = %q, want 'pull'", queue[1].Type)
-	}
-}
-
-func TestGetTriageQueue_EmptyOrgs(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		switch {
-		case r.URL.Path == "/api/v1/user/orgs":
-			json.NewEncoder(w).Encode([]Org{})
-		default:
-			json.NewEncoder(w).Encode([]interface{}{})
-		}
-	}))
-	defer server.Close()
-
-	c := NewClient(server.URL)
-	queue, err := c.GetTriageQueue(context.Background(), "test-token", []string{})
-	if err != nil {
-		t.Fatalf("GetTriageQueue with empty orgs: %v", err)
-	}
-	if len(queue) != 0 {
-		t.Errorf("expected empty queue for empty orgs, got %d items", len(queue))
-	}
-}
-
-func TestGetTriageQueue_AllAssigned(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		switch {
-		case r.URL.Path == "/api/v1/user/orgs":
-			json.NewEncoder(w).Encode([]Org{{Name: "org1"}})
-		case strings.HasPrefix(r.URL.Path, "/api/v1/orgs/org1/repos"):
-			json.NewEncoder(w).Encode([]Repo{
-				{ID: 1, Name: "repo1", FullName: "org1/repo1", Owner: struct {
-					Login string `json:"login"`
-				}{Login: "org1"}},
-			})
-		case strings.HasSuffix(r.URL.Path, "/issues"):
-			// All issues are assigned.
-			json.NewEncoder(w).Encode([]map[string]interface{}{
-				{
-					"id": 1, "number": 1, "title": "Assigned issue",
-					"state": "open",
-					"assignee":  map[string]string{"login": "dev1"},
-					"assignees": []map[string]string{{"login": "dev1"}},
-					"labels":    []interface{}{},
-					"html_url":  "http://example.com/org1/repo1/issues/1",
-				},
-			})
-		case strings.HasSuffix(r.URL.Path, "/pulls"):
-			json.NewEncoder(w).Encode([]interface{}{}) // No PRs.
-		case strings.HasSuffix(r.URL.Path, "/reviews"):
-			json.NewEncoder(w).Encode([]interface{}{})
-		default:
-			json.NewEncoder(w).Encode([]interface{}{})
-		}
-	}))
-	defer server.Close()
-
-	c := NewClient(server.URL)
-	queue, err := c.GetTriageQueue(context.Background(), "test-token", []string{"org1"})
-	if err != nil {
-		t.Fatalf("GetTriageQueue: %v", err)
-	}
-	// Only PRs should appear (none here), all issues are assigned.
-	if len(queue) != 0 {
-		t.Errorf("expected 0 items (all assigned), got %d", len(queue))
-	}
-}
-
-func TestGetTriageQueue_LabelExtraction(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		switch {
-		case r.URL.Path == "/api/v1/user/orgs":
-			json.NewEncoder(w).Encode([]Org{{Name: "org1"}})
-		case strings.HasPrefix(r.URL.Path, "/api/v1/orgs/org1/repos"):
-			json.NewEncoder(w).Encode([]Repo{
-				{ID: 1, Name: "repo1", FullName: "org1/repo1", Owner: struct {
-					Login string `json:"login"`
-				}{Login: "org1"}},
-			})
-		case strings.HasSuffix(r.URL.Path, "/issues"):
-			json.NewEncoder(w).Encode([]map[string]interface{}{
-				{
-					"id": 1, "number": 1, "title": "Multi-label issue",
-					"state": "open", "assignee": nil, "assignees": []interface{}{},
-					"labels": []map[string]interface{}{
-						{"id": 1, "name": "bug", "color": "d73a4a"},
-						{"id": 2, "name": "P1", "color": "ff0000"},
-						{"id": 3, "name": "help wanted", "color": "0e8a16"},
-					},
-					"html_url": "http://example.com/org1/repo1/issues/1",
-				},
-			})
-		case strings.HasSuffix(r.URL.Path, "/pulls"):
-			json.NewEncoder(w).Encode([]interface{}{})
-		case strings.HasSuffix(r.URL.Path, "/reviews"):
-			json.NewEncoder(w).Encode([]interface{}{})
-		default:
-			json.NewEncoder(w).Encode([]interface{}{})
-		}
-	}))
-	defer server.Close()
-
-	c := NewClient(server.URL)
-	queue, err := c.GetTriageQueue(context.Background(), "test-token", []string{"org1"})
-	if err != nil {
-		t.Fatalf("GetTriageQueue: %v", err)
-	}
-	if len(queue) != 1 {
-		t.Fatalf("expected 1 item, got %d", len(queue))
-	}
-	if len(queue[0].Labels) != 3 {
-		t.Errorf("expected 3 labels, got %d: %v", len(queue[0].Labels), queue[0].Labels)
-	}
-}
-
 // --- Issue #122: Tests for ListOrgsAndRepos and CreateIssue ---
 
 func TestListOrgsAndRepos(t *testing.T) {
@@ -1298,3 +1087,161 @@ func TestListAllPullRequests_Pagination(t *testing.T) {
 		t.Error("page 2: HasMore should be false")
 	}
 }
+
+func TestDoRequest_RateLimitRetry(t *testing.T) {
+	attempts := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attempts++
+		if attempts <= 2 {
+			w.Header().Set("Retry-After", "0")
+			w.WriteHeader(http.StatusTooManyRequests)
+			return
+		}
+		w.WriteHeader(http.StatusOK)
+		fmt.Fprint(w, `[{"username":"test-org"}]`)
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL)
+	c.maxRetries = 3
+	c.baseRetryDelay = 1 * time.Millisecond // Fast for tests.
+
+	resp, err := c.doRequest(context.Background(), "test-token", "GET", "/user/orgs", nil)
+	if err != nil {
+		t.Fatalf("expected success after retries, got: %v", err)
+	}
+	resp.Body.Close()
+
+	if attempts != 3 {
+		t.Errorf("expected 3 attempts, got %d", attempts)
+	}
+}
+
+func TestDoRequest_RateLimitExhausted(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusTooManyRequests)
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL)
+	c.maxRetries = 2
+	c.baseRetryDelay = 1 * time.Millisecond
+
+	_, err := c.doRequest(context.Background(), "test-token", "GET", "/user/orgs", nil)
+	if err == nil {
+		t.Fatal("expected error after exhausting retries")
+	}
+	if !strings.Contains(err.Error(), "rate limit exceeded") {
+		t.Errorf("expected rate limit error, got: %v", err)
+	}
+}
+
+func TestDoRequest_RateLimitWithRetryAfterHeader(t *testing.T) {
+	attempts := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attempts++
+		if attempts == 1 {
+			w.Header().Set("Retry-After", "1")
+			w.WriteHeader(http.StatusTooManyRequests)
+			return
+		}
+		w.WriteHeader(http.StatusOK)
+		fmt.Fprint(w, `[]`)
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL)
+	c.maxRetries = 3
+	c.baseRetryDelay = 1 * time.Millisecond
+
+	start := time.Now()
+	resp, err := c.doRequest(context.Background(), "test-token", "GET", "/user/orgs", nil)
+	elapsed := time.Since(start)
+	if err != nil {
+		t.Fatalf("expected success, got: %v", err)
+	}
+	resp.Body.Close()
+
+	// Retry-After: 1 means 1 second delay.
+	if elapsed < 900*time.Millisecond {
+		t.Errorf("expected at least ~1s delay from Retry-After header, got %v", elapsed)
+	}
+}
+
+func TestDoRequest_RateLimitCancelledContext(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Retry-After", "60")
+		w.WriteHeader(http.StatusTooManyRequests)
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL)
+	c.maxRetries = 3
+	c.baseRetryDelay = 1 * time.Millisecond
+
+	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+	defer cancel()
+
+	_, err := c.doRequest(ctx, "test-token", "GET", "/user/orgs", nil)
+	if err == nil {
+		t.Fatal("expected error from cancelled context")
+	}
+}
+
+func TestDoRequest_NonRateLimitErrorNotRetried(t *testing.T) {
+	attempts := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attempts++
+		w.WriteHeader(http.StatusForbidden)
+		fmt.Fprint(w, `{"message":"forbidden"}`)
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL)
+	c.maxRetries = 3
+	c.baseRetryDelay = 1 * time.Millisecond
+
+	_, err := c.doRequest(context.Background(), "test-token", "GET", "/user/orgs", nil)
+	if err == nil {
+		t.Fatal("expected error for 403")
+	}
+	if attempts != 1 {
+		t.Errorf("expected only 1 attempt for non-429 error, got %d", attempts)
+	}
+}
+
+func TestRetryDelay_WithRetryAfterHeader(t *testing.T) {
+	c := NewClient("https://example.com")
+	c.baseRetryDelay = 1 * time.Second
+
+	resp := &http.Response{Header: http.Header{}}
+	resp.Header.Set("Retry-After", "5")
+
+	delay := c.retryDelay(resp, 0)
+	if delay != 5*time.Second {
+		t.Errorf("expected 5s from Retry-After, got %v", delay)
+	}
+}
+
+func TestRetryDelay_ExponentialBackoff(t *testing.T) {
+	c := NewClient("https://example.com")
+	c.baseRetryDelay = 1 * time.Second
+
+	resp := &http.Response{Header: http.Header{}}
+
+	tests := []struct {
+		attempt int
+		want    time.Duration
+	}{
+		{0, 1 * time.Second},
+		{1, 2 * time.Second},
+		{2, 4 * time.Second},
+	}
+
+	for _, tt := range tests {
+		delay := c.retryDelay(resp, tt.attempt)
+		if delay != tt.want {
+			t.Errorf("attempt %d: got %v, want %v", tt.attempt, delay, tt.want)
+		}
+	}
+}