fix(retry): honor the abort signal during the retry backoff

[pacocartones]

This relates to...

No open issue found for this; reported directly with a reproduction.

Rationale

When a retry is scheduled, the default retry policy parks the decision in a
setTimeout backoff (lib/handler/retry-handler.js). An abort that arrives
while that backoff is pending is ignored until the timer elapses. The
consumer's abort reaches the controller of the connection that already
finished — a no-op — and the pending timer is not tracked anywhere, so the
request only rejects with the AbortError after the full backoff: 5 s in the
repro below, and minutes with a large Retry-After (e.g. Retry-After: 120
holds the caller for two minutes). The referenced (non-unref) timer also
keeps the process alive for the whole backoff even though nothing will come of
it.

Reproduced against current main (86b6299): a server that always answers 500,
a RetryAgent with minTimeout: 5000, and abort() fired 800 ms into the
request. The rejection arrives at ~5038 ms instead of ~800 ms.

Changes

• The default retry policy now returns its backoff timer, and the handler
  tracks it while a retry decision is pending (retryPending / retryTimer).
• The RetryController proxy — where every consumer abort already funnels
  through — now also reports abort(reason) to the handler. onAbort cancels
  the pending wait and forwards the abort reason downstream via
  onResponseError immediately (a RequestAbortedError when no reason was
  given, matching api-request's convention).
• Guards make the termination exact: a late decision callback from the policy
  (e.g. a custom retry function resolving after the abort) is ignored, and the
  torn-down connection's late error is not forwarded twice, so the downstream
  handler is errored exactly once.

Both policy call sites (the throwOnError: false response path and the
onResponseError path used by throwOnError: true and network errors) track
the pending decision the same way.

Scope note: a custom retry function that keeps its own timer and does not
return it cannot have that timer cancelled (we were never handed it), but the
abort still settles the request immediately and the late callback is ignored.

Out of scope (deliberately not changed): unref()-ing the backoff timer. A
pending retry is a live logical request; letting the process exit mid-backoff
would silently abandon it. That idea is being explored in #4470, which is
orthogonal to this fix.

Features

N/A

Bug Fixes

• retry() / RetryAgent: an abort that arrives while a retry backoff is
  pending now rejects immediately with the AbortError instead of after the
  full backoff, and no retry is dispatched after the abort.

Breaking Changes and Deprecations

None.

Verification

Every command below was run and its output captured verbatim. The record is
reproducible — the exact commands are included so you can re-run them yourself.

red — main (86b6299) without the fix (must fail: the rejection only comes
after the full backoff)

$ git stash push -- lib/handler/retry-handler.js   # i.e. main's version
$ node --test --test-name-pattern="backoff" test/retry-handler.js
✖ Should abort immediately when aborted during the retry backoff (10028.7502ms)
  AssertionError [ERR_ASSERTION]: rejects long before the 10s backoff elapses
✖ Should ignore a late retry decision after an abort during the backoff (3018.9959ms)
  AssertionError [ERR_ASSERTION]: rejects long before the 3s custom backoff

(The abort is fired while the backoff is pending — the test hooks the retry
policy invocation — yet the request only settles once the 10 s / 3 s timers
elapse.)

green — with the fix (must pass)

$ node --test --test-name-pattern="backoff" test/retry-handler.js
✔ Should abort immediately when aborted during the retry backoff (28.0084ms)
✔ Should ignore a late retry decision after an abort during the backoff (3516.7355ms)
ℹ tests 2
ℹ pass 2
ℹ fail 0

(The second test's ~3.5 s are deliberate: after the immediate rejection it
waits past the custom policy's 3 s timer to assert the late decision is
ignored and no retry is dispatched. The assertions are relational — abort
during backoff → immediate rejection with the abort reason — with margins of
two orders of magnitude, so CI slowness does not flake them.)

standalone reproduction against a live server (RetryAgent with
minTimeout: 5000, server always 500, abort() at 800 ms):

# main:
[server] hit #1 at 19ms
[client] abort() at 803ms
[client] rejected at 5038ms: name=AbortError code=20 msg=This operation was aborted
[client] cleanup done at 5039ms        # process held by the pending timer

# with the fix:
[server] hit #1 at 19ms
[client] abort() at 813ms
[client] rejected at 814ms: name=AbortError code=20 msg=This operation was aborted
[client] cleanup done at 816ms         # timer cancelled, process exits

# control (no abort), main and fixed alike:
[server] hit #1 at 19ms
[server] hit #2 at ~5040ms
[client] resolved status=200 at ~5042ms

area suites with the fix (must pass)

$ node --test test/retry-handler.js test/retry-handler2.js test/retry-agent.js \
       test/retry-handler-controller-proxy.js test/interceptors/retry.js \
       test/client-retry-resume-backpressure.js
ℹ tests 68  ℹ pass 68  ℹ fail 0

$ node --test test/retry-handler.js        # full file, incl. the 2 new tests
ℹ tests 23  ℹ pass 23  ℹ fail 0

$ node --test test/http2-goaway-retry-body.js
ℹ tests 1  ℹ pass 1  ℹ fail 0

lint (must pass)

$ npm run lint
> undici@8.10.0 lint
> eslint --cache
[exit code 0]

Not verified locally: the remaining test suites (npm test runs 14 of them);
left to CI, as this change only touches the retry handler and its tests. No
documentation changes: no existing doc describes abort-during-backoff
behavior, and the fixed behavior now matches the general abort contract;
happy to add a note to docs/docs/api/RetryHandler.md if maintainers want one.

Status

• I have read and agreed to the Developer's Certificate of Origin
• Tested
• Benchmarked (optional)
• Documented
• Review ready
• In review
• Merge ready

---

Implementation and validation used AI assistance; I reviewed the final diff and results.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 90.27778% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.44%. Comparing base (8f9cc1d) to head (b7ed531).

Files with missing lines	Patch %	Lines
lib/handler/retry-handler.js	90.27%	7 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5675      +/-   ##
==========================================
- Coverage   93.46%   93.44%   -0.02%     
==========================================
  Files         110      110              
  Lines       38777    38840      +63     
==========================================
+ Hits        36241    36293      +52     
- Misses       2536     2547      +11     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pacocartones]

Heads-up on the red check: the only failure is test/http2-request-never-settles.js, and its root cause is now identified upstream — nodejs/node#64841, a V8 Maglev SIGSEGV regression in Node ≥ 24.15.0 on Linux, reproduced locally with the issue's recipe (crash log byte-identical to the CI signature; still present on v24.19.0). Not related to this PR's changes; a re-run may pass by luck, but the real fix has to land in Node. (More data in #5674's description.)