diff --git a/docs/assets/qa/github-error-reasons/after.png b/docs/assets/qa/github-error-reasons/after.png new file mode 100644 index 000000000..14738adb2 Binary files /dev/null and b/docs/assets/qa/github-error-reasons/after.png differ diff --git a/docs/assets/qa/github-error-reasons/before.png b/docs/assets/qa/github-error-reasons/before.png new file mode 100644 index 000000000..9419e4eb4 Binary files /dev/null and b/docs/assets/qa/github-error-reasons/before.png differ diff --git a/internal/tracker/github.go b/internal/tracker/github.go index d94d49f7c..692f6322d 100644 --- a/internal/tracker/github.go +++ b/internal/tracker/github.go @@ -103,7 +103,7 @@ func (g *githubClient) request(method, suffix string, input, output any) error { } defer res.Body.Close() if res.StatusCode < 200 || res.StatusCode >= 300 { - return fmt.Errorf("GitHub returned HTTP %d; check the project owner's Git token and repository permissions", res.StatusCode) + return githubResponseError(res) } if output == nil { _, err = io.Copy(io.Discard, io.LimitReader(res.Body, 4<<20)) @@ -112,6 +112,52 @@ func (g *githubClient) request(method, suffix string, input, output any) error { return json.NewDecoder(io.LimitReader(res.Body, 8<<20)).Decode(output) } +func githubResponseError(res *http.Response) error { + status := res.StatusCode + hint := http.StatusText(status) + switch { + case status == http.StatusForbidden || status == http.StatusTooManyRequests: + hint = githubRateLimitHint(res) + if hint == "" { + hint = "check the credentials and repository permissions used for this request" + } + case status == http.StatusUnauthorized: + hint = "check the credentials used for this request" + case status == http.StatusNotFound: + hint = "check that the resource exists and the account has access to it" + case status == http.StatusUnprocessableEntity: + hint = "check the submitted parameters" + case status >= 500: + hint = "GitHub service error, try again later" + } + if hint == "" { + return fmt.Errorf("GitHub returned HTTP %d", status) + } + return fmt.Errorf("GitHub returned HTTP %d (%s)", status, hint) +} + +// GitHub can return 403 for both insufficient permissions and throttling. +func githubRateLimitHint(res *http.Response) string { + delay := res.Header.Get("Retry-After") + exhausted := res.Header.Get("X-RateLimit-Remaining") == "0" + if res.StatusCode != http.StatusTooManyRequests && delay == "" && !exhausted { + var failure struct { + Message string `json:"message"` + } + if err := json.NewDecoder(io.LimitReader(res.Body, 8192)).Decode(&failure); err != nil || + !strings.Contains(strings.ToLower(failure.Message), "rate limit") { + return "" + } + } + if seconds, err := strconv.ParseInt(delay, 10, 64); err == nil && seconds >= 0 { + return fmt.Sprintf("rate limit reached, retry after %d seconds", seconds) + } + if reset, err := strconv.ParseInt(res.Header.Get("X-RateLimit-Reset"), 10, 64); exhausted && err == nil && reset > 0 { + return "rate limit reached, retry after " + time.Unix(reset, 0).UTC().Format("2006-01-02 15:04:05 MST") + } + return "rate limit reached, wait before retrying" +} + type githubPull struct { Number int `json:"number"` URL string `json:"html_url"` diff --git a/internal/tracker/github_response_error_test.go b/internal/tracker/github_response_error_test.go new file mode 100644 index 000000000..fc6039585 --- /dev/null +++ b/internal/tracker/github_response_error_test.go @@ -0,0 +1,50 @@ +package tracker + +import ( + "encoding/json" + "fmt" + "net/http" + "net/http/httptest" + "strings" + "testing" +) + +func TestGitHubRequestExplainsUpstreamErrors(t *testing.T) { + for _, tc := range []struct { + name string + status int + headers map[string]string + message string + want string + }{ + {"primary limit", 403, map[string]string{"X-RateLimit-Remaining": "0", "X-RateLimit-Reset": "1700000000"}, "", "2023-11-14 22:13:20 UTC"}, + {"secondary limit with delay", 403, map[string]string{"Retry-After": "60"}, "", "60 seconds"}, + {"secondary limit in message", 403, nil, "You have exceeded a secondary rate limit", "rate limit"}, + {"too many requests", 429, nil, "", "rate limit"}, + {"invalid delay", 429, map[string]string{"Retry-After": "-1"}, "", "wait before retrying"}, + {"bad credentials", 401, nil, "", "credentials"}, + {"forbidden", 403, map[string]string{"X-RateLimit-Remaining": "13"}, "Resource not accessible", "permissions"}, + {"not found", 404, nil, "", "resource exists"}, + {"invalid input", 422, nil, "", "parameters"}, + {"service unavailable", 503, nil, "", "try again later"}, + } { + t.Run(tc.name, func(t *testing.T) { + const privateText = "private-diagnostic-text" + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + for key, value := range tc.headers { + w.Header().Set(key, value) + } + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(tc.status) + _ = json.NewEncoder(w).Encode(map[string]string{"message": tc.message + " " + privateText}) + })) + t.Cleanup(srv.Close) + client := githubClient{http: srv.Client(), base: srv.URL, path: "example/orders"} + err := client.request(http.MethodGet, "/issues", nil, nil) + if err == nil || !strings.Contains(err.Error(), fmt.Sprintf("HTTP %d", tc.status)) || + !strings.Contains(err.Error(), tc.want) || strings.Contains(err.Error(), privateText) { + t.Fatalf("unexpected error: %v", err) + } + }) + } +}