feat(upload): add single-file connection-fault retry opt-out by ffumero2003 · Pull Request #370 · backblaze-labs/b2-sdk-typescript

ffumero2003 · 2026-11-06T21:31:51Z

Context

Add an escape hatch for single-file upload connection-fault retries while retaining normal recovery. Replaying a POST that B2 already stored can create duplicate versions, and Object Lock retention or legal hold can prevent deleting them.

The default remains on. The default-on versus opt-in decision is pending the team's sign-off; this PR only adds the escape hatch.

Root cause

The upload retry helper treated every non-SSRF, non-response-body NetworkError as retryable. Disabling connection-fault replay required setting retry.maxRetries: 0, which also disabled server, auth-token, and upload-URL recovery.

Changes

Add retryUploadConnectionFaults (default true) to client and per-upload options. Per-call values override the client default, including an explicit true.
Mirror retryResponseBodyFailures plumbing with a default resolver, a required resolved upload-layer boolean, and forwarding through the part helper and all multipart/write-stream call sites. The single-file phase gate preserves multipart behavior.
Apply false only to single-file upload-callback connection faults, including wrapped transport errors and timeouts before response headers. Preserve upload-URL acquisition, server/auth/upload-URL retries, backoff, SSRF handling, and multipart/write-stream retry policy. Multipart retries replace the same part number.
Keep successful-response body failures and body-read timeouts under the independent retryResponseBodyFailures option. Enabling that option can still replay a stored POST with connection-fault retries disabled; this is not an exactly-once guarantee.
Document configuration, precedence, duplicate-version risks, and the response-header/body boundary in README, MIGRATION, CHANGELOG, and API TSDoc. The migration example typechecks against the built package declarations.

Verification

pnpm install --frozen-lockfile && pnpm run verify passed:

Already up to date
Done in 122ms using pnpm v11.1.0
CSpell: Files checked: 269, Issues found: 0 in 0 files.
audit wrapper tests: 7 passed, 0 failed
SDK harness unit tests: 192 passed, 0 failed
Test Files  88 passed (88)
     Tests  2621 passed | 9 skipped (2630)
verify-package-exports: OK (48 files referenced, 12 .d.cts entries, 12 subpath probes, dual-format resolve at v0.4.0)

The gate also passed lint, TSDoc lint, typecheck, example typecheck, build, generated docs, and package/release/docs-consistency checks. Biome emitted its existing schema-version informational diagnostic; no warning or error failed the gate. The audit counts above are wrapper tests, not a separate live dependency audit.

New focused regressions: 37 passed, including resolver defaults, default/client/per-call precedence, post-storage connection loss, wrapped errors, actual header/body timeout phases, retained 503/auth/bad-URL recovery, URL-fetch recovery, SSRF refusal, and unchanged multipart/write-stream retries. The focused and existing upload-coverage files passed all 172 tests together.
Focused Chromium/Firefox/WebKit run: 111 passed across three browser files.
Coverage run: 2654 passed, 9 skipped; statements 97.20%, branches 92.62%, functions 98.17%, lines 98.67%. Gates unchanged.
Before implementation: 10 failed, 20 passed in the initial 30-test regression set. Four compatibility cases and three resolver cases were added afterward; before adding the resolver, its three new cases failed because it was missing.

Each mutation below was applied alone, failed its targeted assertions, and was reverted. The restored focused suite passed all 37 tests.

Isolated break	Failing tests
Remove the connection-fault decision	11
Drop small-file helper forwarding	1
Ignore the client default	2
Drop bucket per-call forwarding	3
Drop file per-call forwarding	3
Apply the opt-out to upload-URL acquisition	2
Apply the opt-out to multipart parts	1
Change the omitted-option default to off	1
Disable server/auth/bad-upload-URL recovery	3

The resolved-option follow-up also rechecked the return true mutation (11 failed, 26 passed) and a resolver default of false (1 failed, 2 passed). Removing uploadPartWithFreshUrl forwarding failed typecheck with TS2345, because the resolved field is required; restoring it passed typecheck and full verification.

Test limit: the simulator does not persist single-file retention headers. The Object Lock-enabled case verifies the enabled bucket, outgoing retention settings, and one stored version; it does not prove server-side retention enforcement. No live B2 run is claimed.

Closes #368

quality-keeper · 2026-11-06T21:34:33Z

Quality Keeper — Advisory Review

Source: backblaze-labs/b2-sdk-typescript

Advisory only — this is not a required status check. Quality Keeper reviewed this repository snapshot and is reporting what it found. It changes no status and merges nothing; suggested scaffolds are starting points, not proof.

Quality Keeper assessed the repository, executed checks, and collected results, covering 19 quality expectations.

Five repository-quality areas

Hard expectations keep their exact Evidence State. Advisory applicability questions are separate. Implementation or suite presence is not proof of a trusted run.

Area	Hard expectations	Evidence States	Implementation status
Observability	0	—	`not_evaluated` 1
Product Analytics	0	—	`not_evaluated` 1
User Feedback	0	—	`not_evaluated` 1
Reliability	3	`pending_run` 3	`not_evaluated` 3
Security	4	`pending_run` 2, `verified` 2	`not_evaluated` 4
Other registered quality	12	`pending_run` 10, `verified` 2	`not_evaluated` 12

Observability — 0 hard, 0 advisory

Can operators understand and diagnose repository-owned runtime behavior?

Hard expectations

None selected.