fix(client): back off when Retry-After is zero or not in the future

[bestend]

Problem

The retry interceptor honors Retry-After literally, so Retry-After: 0 produces a 0 ms delay.

Confluence Data Center's rate limiter (a token bucket) sends Retry-After: 0 on 429 responses, and on 200 responses, together with x-ratelimit-limit: 3, x-ratelimit-fillrate: 3 and x-ratelimit-interval-seconds: 1. Every retry therefore fired immediately, hit the empty bucket again, and all attempts were used up within milliseconds. On Data Center 9.2.9 (3 requests per second), confluence children <pageId> --recursive sent 36 requests in 186 ms and failed with Rate limit exceeded.

A negative value, a whitespace-only value and an HTTP-date that is not in the future also resolved to 0 ms.

Fix

retryDelayMs honors Retry-After only when it names a positive wait: a positive number of seconds or a future HTTP-date, still capped at 60 s. A missing, unparsable, zero, negative or already-past value is treated like a missing header and falls back to the existing exponential backoff (1 s, 2 s, 4 s with the default base delay, capped at 60 s). Positive values behave exactly as before.

• The x-ratelimit-* headers are deliberately not used as a hint. While Retry-After is positive they add nothing, and the 1 s base backoff already spans the 1 s refill interval reported next to Retry-After: 0.
• No extra minimum delay was added: with the default base of 1000 ms the backoff is never below 1 s; it is only small when tests inject a tiny retryBaseDelayMs.

Verification

• Added 12 unit tests: Retry-After of "0", numeric 0, "00", whitespace, negative seconds, unparsable text and an empty string; past and current HTTP-dates; positive seconds and future HTTP-dates (still honored and capped); the backoff cap; and the interceptor wiring, asserting the sleep durations for a 429 with Retry-After: 0 (1000, 2000) and with Retry-After: 3 (3000) without waiting in real time. 8 of them fail on main (the interceptor test sees [0, 0]); the other 4 guard existing behavior.
• npm test: 1465 passed (1453 before). npm run lint: clean.
• Simulated a local 3 requests/second token-bucket server that answers Retry-After: 0 on every response and ran getAllDescendantPages over a tree needing 36 requests: main fails after about 15 ms with 3 of 36 requests served; this branch spaces retries 1 s / 2 s / 4 s and serves 24 before failing.
• On the Data Center 9.2.9 server, children <pageId> --recursive --max-depth 3 gives up after 0.3 s on v2.25.8 and after 7.3 s on this branch: the retries now wait, but the traversal still fails for the reason below.

Known limitation

This fixes the retry timing only. children --recursive runs up to 10 requests concurrently, which does not fit under 3 requests per second with 3 retries (7 s of waiting). In the same simulation, limiting the traversal to 3 concurrent requests completes the 36-request tree in about 11 s, and raising maxRetries to 10 completes it in about 15 s; jitter alone does not help. Both are behavior changes, so they are left for a follow-up.

Type of Change

• Bug fix (non-breaking change which fixes an issue)

Testing

• Tests pass locally with my changes
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings

🤖 Generated with Claude Code

[pchuri]

Thanks for the clear diagnosis and focused fix. Falling back to the existing exponential backoff when Retry-After provides no usable positive delay makes sense, while preserving positive delays and the existing cap.

I reviewed the current head and ran the client test suite (268/268 passing) and lint successfully. I did not find a blocking issue in the reviewed changes. I also appreciate the explicit note that recursive traversal can still exceed a low rate limit: concurrency and retry-budget changes can remain a separate follow-up rather than expanding this PR.

I have not independently repeated the live-server/simulation checks or run the full repository test suite yet. This looks ready to move toward merge after final validation. Thanks again!

[github-actions]

🎉 This PR is included in version 2.25.9 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀