110 lines
3.5 KiB
Markdown
110 lines
3.5 KiB
Markdown
---
|
|
id: "01-rate-aware-api-recovery"
|
|
title: "Add rate-aware API recovery"
|
|
status: done
|
|
wave: 1
|
|
depends_on: []
|
|
plan: "plan.md"
|
|
requirements:
|
|
- REQ-CI-PR-DOCS-003
|
|
acceptance_criteria:
|
|
- AC-CI-PR-DOCS-003.6
|
|
- AC-CI-PR-DOCS-003.7
|
|
system_design:
|
|
- ../../specs/ci/system-design/pull-request-documentation-coverage.md
|
|
---
|
|
|
|
# Task 01: Add rate-aware API recovery
|
|
|
|
## Summary
|
|
|
|
Make the custom documentation evaluator recover from transient GitHub failures
|
|
and expose useful, sanitized failure diagnostics.
|
|
|
|
## In scope
|
|
|
|
- `.github/scripts/pr-docs.cjs`
|
|
- `.github/scripts/pr-docs.test.cjs`
|
|
- This work order's implementation results
|
|
|
|
## Out of scope
|
|
|
|
Request consolidation, workflow trigger changes, size-label behavior, token
|
|
changes, and live GitHub mutations outside normal workflow status publication.
|
|
|
|
## Acceptance
|
|
|
|
- Make at most three attempts for classified transport, 408, 429, retryable
|
|
5xx, and rate-limit 403 errors. Fail permanent client errors immediately.
|
|
- Honor usable `Retry-After` and primary reset headers. Use 60 then 120 seconds
|
|
for a secondary rate limit without usable guidance, with a 180-second total
|
|
sleep budget.
|
|
- Log bounded request class, status/category, attempt, delay, and stop reason.
|
|
Never log credentials, response bodies, query text, or document contents.
|
|
|
|
## Verification
|
|
|
|
Run from the repository root:
|
|
|
|
```bash
|
|
node --test .github/scripts/pr-docs.test.cjs
|
|
python3 .github/scripts/pr-docs-workflow-contract_test.py
|
|
git diff --check
|
|
```
|
|
|
|
## Files likely touched
|
|
|
|
- `.github/scripts/pr-docs.cjs`
|
|
- `.github/scripts/pr-docs.test.cjs`
|
|
- `docs/plans/github-api-resilience/task-01-rate-aware-api-recovery.md`
|
|
|
|
## Dependencies
|
|
|
|
None. Reconcile and reuse PR #3693 rather than independently duplicating its
|
|
client and diagnostic changes.
|
|
|
|
## Risks
|
|
|
|
Do not apply the short transport/server backoff to a secondary rate limit.
|
|
Retry status writes only with the exact original payload.
|
|
|
|
## Parallelism
|
|
|
|
`sequential`
|
|
|
|
## Inputs
|
|
|
|
- [Requirements](../../specs/ci/requirements/pull-request-documentation-coverage.md)
|
|
- [System design](../../specs/ci/system-design/pull-request-documentation-coverage.md)
|
|
- [Plan](plan.md)
|
|
- [PR #3693](https://github.com/kdlbs/kandev/pull/3693)
|
|
|
|
## Results
|
|
|
|
Implemented the bounded GitHub API client recovery path in
|
|
`.github/scripts/pr-docs.cjs` and covered it with focused fixtures in
|
|
`.github/scripts/pr-docs.test.cjs`.
|
|
|
|
- Classified transport and timeout failures, HTTP 408, 429, retryable 5xx,
|
|
rate-limit 403 responses, and merge-queue GraphQL `RATE_LIMITED` payloads for
|
|
at most three attempts.
|
|
- Shared the 180-second sleep budget across every request made by one client
|
|
evaluation.
|
|
- Permanent 4xx responses fail immediately when their body cannot be read or
|
|
contains invalid JSON.
|
|
- Honored numeric and date `Retry-After` values and primary reset headers.
|
|
Secondary rate-limit responses without usable headers wait 60 seconds and
|
|
then 120 seconds, within a 180-second total sleep budget.
|
|
- Added bounded request-class diagnostics for retries, permanent failures,
|
|
exhausted attempts, and wait-budget stops. Diagnostics contain no tokens,
|
|
query text, response bodies, or document contents.
|
|
|
|
Verification:
|
|
|
|
- `node --test .github/scripts/pr-docs.test.cjs` (75 passed)
|
|
- `python3 .github/scripts/pr-docs-workflow-contract_test.py` (7 passed)
|
|
- `python3 .github/scripts/lint-action-pinning_test.py` (9 passed)
|
|
- `python3 .github/scripts/lint-action-pinning.py` (24 workflows passed)
|
|
- `zizmor .github/workflows/pr-docs.yml` (no findings)
|
|
- `git diff --check` (passed)
|