Skip to content

Announce the wait when the GitHub rate limit is reached - #64

Merged
dmccoystephenson merged 1 commit into
mainfrom
feature/announce-rate-limit-wait
Nov 7, 2026
Merged

dmccoystephenson merged 1 commit into
mainfrom
feature/announce-rate-limit-wait

Conversation

@dmccoystephenson

@dmccoystephenson dmccoystephenson commented Nov 7, 2026 •

Copy link
Copy Markdown
Member

Summary

  • A notice is now printed to standard error when the GitHub rate limit is reached, before the client's wait begins. It names the expected reset time and, for anonymous access, suggests GITHUB_TOKEN. Previously the run stalled with no output for up to an hour and looked hung.
  • The waiting itself is unchanged. RateLimitNoticeHandler delegates to github-api's own RateLimitHandler.WAIT after printing. Failing instead was rejected, because it would drop the remaining users of a daemon run until the next interval.
  • The anonymous client is now built with GitHubBuilder rather than GitHub.connectAnonymously(), since that method accepts no handler. The handler is installed on the token client, the anonymous client, and the fallback after a rejected token.
  • The comment in GitHubService that said a rate limit propagates as an error was corrected.
  • USER_GUIDE.md, COMMANDS.md (the POST /api/backups request stays open during a wait) and CHANGELOG.md were updated. No flag, property or endpoint was added.

Closes #63

Evidence

The wait was observed by running github-api 1.318 against a loopback stub, recorded in #63. The same stub (a scratch test, not committed) was then used with the new handler. The notice was printed, the wait ran, and the retry succeeded with two requests received, so the real client does call the handler and the X-RateLimit-Reset header is read as expected.

Not covered

GitHub's secondary (abuse) limits go through a separate default handler that also waits silently. They were left alone: the few list requests of a run are unlikely to reach them.

The reset time in the notice is approximate. The stub run resumed about 8 seconds after a reset 2 seconds ahead, so the notice says "until about".

Skipped issues

#8 (missing LICENSE file) was not picked: a license and copyright holder have to be chosen by the maintainer, as recorded on that issue.

Test plan

  • mvn test: 222 tests run, 0 failures, 1 skipped (the live-token test, which needs GITHUB_TOKEN)
  • Regression check: with the handler wiring removed from GitHubService, the 3 new wiring tests failed; they passed again once it was restored
  • Build workflow is green on the PR head (build and docker-build on b01b4ba)

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code


drafted by Claude on behalf of Daniel Stephenson

The GitHub client waits silently for the limit to reset, for up to an
hour, so a run that reached it looked hung. A comment in GitHubService
also claimed the limit propagated as an error, which it does not.

Print a notice with the expected reset time before the unchanged wait,
and suggest GITHUB_TOKEN when running anonymously.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dmccoystephenson

Copy link
Copy Markdown
Member Author

Self-review rubric, scored against head b01b4ba (not an independent review):

  • Scope: PASS. Every changed file is needed for A backup that reaches the GitHub rate limit stalls silently for up to an hour #63: the handler, its wiring, the corrected comment, the tests, and three docs.
  • Tests-new: PASS, with one gap noted below. RateLimitNoticeHandler has 7 tests in its mirror file, and the wiring has 3 in GitHubServiceTest.
  • Tests-fix: PASS. With the withRateLimitHandler calls removed from GitHubService, mvn test -Dtest=GitHubServiceTest gave 19 run, 3 failures, all three new wiring tests. They passed again once the calls were restored.
  • Sibling structure: PASS. The new class sits beside GitHubService in com.github.backup, and the test file follows the @Mock plus openMocks pattern and test<Method>_<Scenario> naming.
  • Sibling renames: PASS. Nothing was renamed.
  • Docs: PASS. USER_GUIDE.md, COMMANDS.md and CHANGELOG.md describe the notice and the wait. README.md and CONFIG.md make no claim about reaching the limit, so they are unchanged.
  • Issue resolution: PASS. The notice, the corrected comment and the documentation asked for in A backup that reaches the GitHub rate limit stalls silently for up to an hour #63 are all in the diff.
  • CI: PASS. build and docker-build are green on b01b4ba.
  • Config-doc parity: PASS. No property was added.
  • Command-doc parity: PASS. No flag, system property or endpoint was added.
  • Package placement: PASS. src/main/java/com/github/backup/RateLimitNoticeHandler.java is a core class under com.github.backup.
  • No credential leakage: PASS. The notice contains only the reset time and the variable name GITHUB_TOKEN, never its value.

Notes:

  • src/main/java/com/github/backup/RateLimitNoticeHandler.java:27 — the one-argument constructor's defaults (System.err, RateLimitHandler.WAIT) are not asserted by a committed test. A unit test using them would really sleep. The real wait was exercised once through the scratch loopback stub described in the PR body, with the output stream injected.
  • src/main/java/com/github/backup/GitHubService.java:55 — the anonymous client is now built with GitHubBuilder instead of GitHub.connectAnonymously(), so the mocks in GitHubServiceTest changed along with it. The existing token and fallback tests still pass against the rewritten helper.
  • Tests-fix could not cover the handler itself by reverting it, since its tests do not compile without the class. Reverting the wiring is the check that was run.
  • A 403 rate-limit response to the startup token check also waits, with the same notice, rather than printing Could not verify GITHUB_TOKEN. That wait predates this PR.

Summary: no blocking findings. The notes above were judged acceptable for merge.

This comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).


drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson
dmccoystephenson merged commit a2e9695 into main Nov 7, 2026
2 checks passed
@dmccoystephenson
dmccoystephenson deleted the feature/announce-rate-limit-wait branch November 7, 2026 07:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A backup that reaches the GitHub rate limit stalls silently for up to an hour

1 participant