[Ian Clanton-Thuon (iclanton)]

Summary

• Retry transient transport errors, including ECONNRESET, rather than bypassing the HTTP cache retry budget when a request throws.
• Make file-stream uploads replayable by opening a fresh stream for each attempt and destroying failed request/response streams.
• Retry transient HTTP responses, including Cloudflare 520-524, while avoiding retries for cache misses and permanent authentication/configuration errors.
• Add bounded exponential backoff with jitter, support both Retry-After forms, and include attempt/delay and cf-ray diagnostics.
• Document the retry policy and idempotent cache-write requirement.

Why

The HTTP cache provider already retries buffered uploads that receive unsuccessful HTTP responses, but transport exceptions escape directly to the outer warning handler. Streamed uploads explicitly make only one attempt because their request body cannot be replayed. Brief cache-service interruptions can therefore fail an otherwise successful build and require rerunning the whole pipeline.

Both upload paths now share the existing three-attempt budget. File uploads create their stream inside the attempt, so a failed upload cannot leave the next attempt with an already-consumed body.

Behavior and scope

• Retries cover transient network errors and HTTP 408, 429, 500, 502, 503, 504, and 520-524.
• The first backoff is 2.5-5 seconds, then 5-10 seconds, with a 60-second maximum delay.
• Retry-After can increase the delay. If the requested wait exceeds 60 seconds, report the failure rather than retrying before the requested time or imposing an unbounded wait.
• The existing credential challenge flow and exhausted-failure severity remain in place.
• Transient retry diagnostics use verbose output, so a recovered request does not emit a build-failing warning.
• No new configuration knobs or changes to the overall cache-failure policy are included.
• Custom POST/PATCH cache writes, like PUT writes, must be idempotent for a cache key; the server may have committed a write before its response is lost.

Validation

• node common/scripts/install-run-rush.js build: 146 operations succeeded.
• node common/scripts/install-run-rush.js retest --only @rushstack/rush-http-build-cache-plugin --verbose: 114 tests passed.
• Real local-HTTP tests verify complete stream replay after HTTP 520, an early HTTP 520 before the body is consumed, and a connection reset.
• Regression tests cover retry exhaustion, mixed HTTP/transport failures, permanent errors, backoff/jitter, both Retry-After formats and bounds, stream cleanup, and diagnostics.
• Mutation check: disabling streamed retries and ECONNRESET retries causes 39 tests to fail; restoring the implementation returns the suite to green.
• node common/scripts/install-run-rush.js change --verify --target-branch microsoft/main: passed.