@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/upload/retry.cjs

@@ -0,0 +1,186 @@
+const require_errors_index = require("../errors/index.cjs");
+const require_retry = require("../http/retry.cjs");
+//#region src/upload/retry.ts
+var freshUrlRetryOverride = { maxRetries: 0 };
+/**
+* Resolves the public default for `retryResponseBodyFailures`. Callers must
+* opt into replaying ambiguous upload POST failures for every upload mode.
+*
+* @param value - Caller-provided override, if any.
+*
+* @returns The boolean value passed to the upload retry helper.
+*/
+function resolveRetryResponseBodyFailures(value) {
+	return value ?? false;
+}
+/**
+* Fetches a small-file upload URL, bypassing the pool.
+*
+* @param raw - Low-level B2 API client.
+* @param accountInfo - Authorized account state.
+* @param bucketId - Bucket to upload into.
+* @param signal - Optional abort signal for the fresh URL request.
+*
+* @returns A fresh upload URL entry.
+*/
+async function fetchFreshUploadUrl(raw, accountInfo, bucketId, signal) {
+	const resp = await raw.getUploadUrl(accountInfo.getApiUrl(), accountInfo.getAuthToken(), { bucketId }, {
+		...signal !== void 0 ? { signal } : {},
+		retry: freshUrlRetryOverride
+	});
+	return {
+		uploadUrl: resp.uploadUrl,
+		authorizationToken: resp.authorizationToken
+	};
+}
+/**
+* Fetches a large-file part upload URL, bypassing the pool.
+*
+* @param raw - Low-level B2 API client.
+* @param accountInfo - Authorized account state.
+* @param fileId - Large file to upload a part into.
+* @param signal - Optional abort signal for the fresh URL request.
+*
+* @returns A fresh part upload URL entry.
+*/
+async function fetchFreshPartUploadUrl(raw, accountInfo, fileId, signal) {
+	const resp = await raw.getUploadPartUrl(accountInfo.getApiUrl(), accountInfo.getAuthToken(), { fileId }, {
+		...signal !== void 0 ? { signal } : {},
+		retry: freshUrlRetryOverride
+	});
+	return {
+		uploadUrl: resp.uploadUrl,
+		authorizationToken: resp.authorizationToken
+	};
+}
+/**
+* Uploads one multipart part with fresh-URL retry.
+*
+* @param raw - Low-level B2 API client.
+* @param accountInfo - Authorized account state.
+* @param fileId - Large file to upload a part into.
+* @param options - Part upload parameters and retry settings.
+*
+* @returns The uploaded part response.
+*/
+function uploadPartWithFreshUrl(raw, accountInfo, fileId, options) {
+	return withFreshUploadUrlRetry({
+		fileName: options.fileName,
+		partNumber: options.partNumber,
+		retry: options.retry,
+		signal: options.signal,
+		onUploadRetry: options.onUploadRetry,
+		retryResponseBodyFailures: options.retryResponseBodyFailures,
+		checkout: () => accountInfo.checkoutPartUploadUrl(fileId),
+		fetchFresh: () => fetchFreshPartUploadUrl(raw, accountInfo, fileId, options.signal),
+		returnEntry: (entry) => accountInfo.returnPartUploadUrl(fileId, entry),
+		evictEntry: (entry) => accountInfo.evictPartUploadUrl(fileId, entry),
+		upload: (entry) => raw.uploadPart(entry.uploadUrl, {
+			authorization: entry.authorizationToken,
+			partNumber: options.partNumber,
+			contentLength: options.contentLength,
+			contentSha1: options.contentSha1,
+			...options.serverSideEncryption !== void 0 ? { serverSideEncryption: options.serverSideEncryption } : {}
+		}, options.data, {
+			...options.signal !== void 0 ? { signal: options.signal } : {},
+			...options.retry !== void 0 ? { retry: options.retry } : {}
+		})
+	});
+}
+/**
+* Runs an upload operation with B2's documented retry flow: evict the failed
+* upload URL, back off, fetch a fresh upload URL, and retry there.
+*
+* For single-request file uploads, sending the POST again after a lost success
+* response can create a duplicate file version. Multipart retries re-send the
+* same part number instead. Response-body retry defaults are caller-specific:
+* single-request uploads keep them off by default, while multipart callers can
+* opt in with `retryResponseBodyFailures: true` when replaying the same part
+* number is acceptable.
+*
+* @param options - URL checkout, upload, eviction, and retry callbacks.
+*
+* @returns The successful upload result.
+*/
+async function withFreshUploadUrlRetry(options) {
+	const retryOptions = {
+		...require_retry.DEFAULT_RETRY_OPTIONS,
+		...options.retry
+	};
+	for (let attempt = 0; attempt <= retryOptions.maxRetries; attempt++) {
+		let uploadEntry;
+		let uploadStarted = false;
+		try {
+			options.signal?.throwIfAborted();
+			uploadEntry = attempt === 0 ? options.checkout() ?? await options.fetchFresh() : await options.fetchFresh();
+			uploadStarted = true;
+			const result = await options.upload(uploadEntry);
+			options.returnEntry(uploadEntry);
+			return result;
+		} catch (err) {
+			const retryError = normalizeUploadRetryError(err, options);
+			if (uploadEntry !== void 0) if (isUploadRateLimitError(retryError)) options.returnEntry(uploadEntry);
+			else options.evictEntry(uploadEntry);
+			if (options.signal?.aborted) throw err;
+			if (isUploadRateLimitError(retryError) && uploadEntry !== void 0) throw retryError;
+			if (!isUploadRetryable(retryError, {
+				...options,
+				uploadStarted
+			}) || attempt === retryOptions.maxRetries) throw retryError;
+			const retryAttempt = attempt + 1;
+			const retryAfter = retryError instanceof require_errors_index.B2Error ? retryError.retryAfter : void 0;
+			const delayMs = require_retry.computeBackoff(attempt, retryOptions, retryAfter);
+			notifyUploadRetry(options, {
+				fileName: options.fileName,
+				partNumber: options.partNumber,
+				attempt: retryAttempt,
+				maxRetries: retryOptions.maxRetries,
+				delayMs,
+				error: retryError
+			});
+			await require_retry.sleep(delayMs, options.signal);
+		}
+	}
+	/* v8 ignore next -- defensive return-path guard. */
+	throw new require_errors_index.NetworkError("Upload retry budget exhausted");
+}
+function notifyUploadRetry(options, event) {
+	try {
+		options.onUploadRetry?.(event);
+	} catch {}
+}
+function isUploadRetryable(err, options) {
+	if (err instanceof require_errors_index.NetworkError) {
+		if (err.cause instanceof require_errors_index.B2SsrfError) return false;
+		if (!options.uploadStarted) return true;
+		return options.retryResponseBodyFailures === true;
+	}
+	if (err instanceof require_errors_index.BadAuthTokenError) return true;
+	if (isUploadUrlInvalidationError(err)) return true;
+	return err instanceof require_errors_index.B2Error && err.retryable;
+}
+function isUploadRateLimitError(err) {
+	return err instanceof require_errors_index.B2Error && err.status === 429;
+}
+function normalizeUploadRetryError(err, options) {
+	if (err instanceof require_errors_index.B2Error || err instanceof require_errors_index.NetworkError) return err;
+	if (err instanceof require_errors_index.UploadResponseBodyError) {
+		if (!options.retryResponseBodyFailures) return err;
+		return new require_errors_index.NetworkError(err.message, err);
+	}
+	if (err instanceof DOMException && err.name === "AbortError") return err;
+	if (err instanceof TypeError || err instanceof SyntaxError || err instanceof DOMException) return new require_errors_index.NetworkError(err instanceof Error ? err.message : "Upload response read failed", err);
+	return err;
+}
+function isUploadUrlInvalidationError(err) {
+	if (err instanceof require_errors_index.BadUploadUrlError) return true;
+	return err instanceof require_errors_index.BadRequestError && /upload url/i.test(err.message);
+}
+//#endregion
+exports.fetchFreshPartUploadUrl = fetchFreshPartUploadUrl;
+exports.fetchFreshUploadUrl = fetchFreshUploadUrl;
+exports.resolveRetryResponseBodyFailures = resolveRetryResponseBodyFailures;
+exports.uploadPartWithFreshUrl = uploadPartWithFreshUrl;
+exports.withFreshUploadUrlRetry = withFreshUploadUrlRetry;
+
+//# sourceMappingURL=retry.cjs.map

package/dist/upload/retry.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.cjs","names":[],"sources":["../../src/upload/retry.ts"],"sourcesContent":["import type { AccountInfo, UploadUrlEntry } from '../auth/account-info.ts'\nimport {\n  B2Error,\n  B2SsrfError,\n  BadAuthTokenError,\n  BadRequestError,\n  BadUploadUrlError,\n  NetworkError,\n  UploadResponseBodyError,\n} from '../errors/index.ts'\nimport { computeBackoff, DEFAULT_RETRY_OPTIONS, type RetryOptions, sleep } from '../http/retry.ts'\nimport type { RawClient } from '../raw/index.ts'\nimport type { EncryptionSetting } from '../types/encryption.ts'\nimport type { BucketId, LargeFileId } from '../types/ids.ts'\nimport type { UploadPartResponse } from '../types/upload.ts'\n\n/** Event emitted before an upload is retried against a fresh upload URL. */\nexport interface UploadRetryEvent {\n  /** File name being uploaded. */\n  readonly fileName: string\n  /** Multipart part number, or `null` for a single-request file upload. */\n  readonly partNumber: number | null\n  /** One-based retry attempt that is about to run. */\n  readonly attempt: number\n  /** Maximum number of retry attempts allowed for this upload operation. */\n  readonly maxRetries: number\n  /** Backoff delay in milliseconds before the fresh URL is fetched. */\n  readonly delayMs: number\n  /** Classified error that triggered the fresh-URL retry. */\n  readonly error: B2Error | NetworkError\n}\n\n/** Callback invoked before an upload retry fetches a fresh upload URL. */\nexport type UploadRetryListener = (event: UploadRetryEvent) => void\n\n/** Shared public options for upload-layer fresh-URL retries. */\nexport interface UploadRetryOptions {\n  /** Retry settings shared with the main transport retry configuration. */\n  readonly retry?: Partial<RetryOptions> | undefined\n  /** Callback invoked before a fresh-URL upload retry. */\n  readonly onUploadRetry?: UploadRetryListener | undefined\n  /**\n   * Whether ambiguous failures after an upload POST should be retried,\n   * including response-body read failures and transport errors where B2 may\n   * have stored the payload before the success response was lost.\n   * Defaults to false. Set true only when duplicate versions or parts are\n   * acceptable.\n   */\n  readonly retryResponseBodyFailures?: boolean | undefined\n}\n\ninterface UploadLayerRetryOptions extends Omit<UploadRetryOptions, 'retryResponseBodyFailures'> {\n  readonly retryResponseBodyFailures: boolean\n  /** Abort signal for cancelling upload attempts and retry backoff sleeps. */\n  readonly signal?: AbortSignal | undefined\n}\n\ninterface FreshUrlRetryOptions<T> extends UploadLayerRetryOptions {\n  readonly fileName: string\n  readonly partNumber: number | null\n  readonly checkout: () => UploadUrlEntry | null\n  readonly fetchFresh: () => Promise<UploadUrlEntry>\n  readonly returnEntry: (entry: UploadUrlEntry) => void\n  readonly evictEntry: (entry: UploadUrlEntry) => void\n  readonly upload: (entry: UploadUrlEntry) => Promise<T>\n}\n\nconst freshUrlRetryOverride: Partial<RetryOptions> = { maxRetries: 0 }\n\n/**\n * Resolves the public default for `retryResponseBodyFailures`. Callers must\n * opt into replaying ambiguous upload POST failures for every upload mode.\n *\n * @param value - Caller-provided override, if any.\n *\n * @returns The boolean value passed to the upload retry helper.\n */\nexport function resolveRetryResponseBodyFailures(value: boolean | undefined): boolean {\n  return value ?? false\n}\n\n/**\n * Fetches a small-file upload URL, bypassing the pool.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param bucketId - Bucket to upload into.\n * @param signal - Optional abort signal for the fresh URL request.\n *\n * @returns A fresh upload URL entry.\n */\nexport async function fetchFreshUploadUrl(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  bucketId: BucketId,\n  signal?: AbortSignal,\n): Promise<UploadUrlEntry> {\n  const resp = await raw.getUploadUrl(\n    accountInfo.getApiUrl(),\n    accountInfo.getAuthToken(),\n    {\n      bucketId,\n    },\n    {\n      ...(signal !== undefined ? { signal } : {}),\n      retry: freshUrlRetryOverride,\n    },\n  )\n  return { uploadUrl: resp.uploadUrl, authorizationToken: resp.authorizationToken }\n}\n\n/**\n * Fetches a large-file part upload URL, bypassing the pool.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param fileId - Large file to upload a part into.\n * @param signal - Optional abort signal for the fresh URL request.\n *\n * @returns A fresh part upload URL entry.\n */\nexport async function fetchFreshPartUploadUrl(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  fileId: LargeFileId,\n  signal?: AbortSignal,\n): Promise<UploadUrlEntry> {\n  const resp = await raw.getUploadPartUrl(\n    accountInfo.getApiUrl(),\n    accountInfo.getAuthToken(),\n    {\n      fileId,\n    },\n    {\n      ...(signal !== undefined ? { signal } : {}),\n      retry: freshUrlRetryOverride,\n    },\n  )\n  return { uploadUrl: resp.uploadUrl, authorizationToken: resp.authorizationToken }\n}\n\ninterface UploadPartWithFreshUrlOptions extends UploadLayerRetryOptions {\n  /** File name associated with the large-file upload. */\n  readonly fileName: string\n  /** One-based part number. */\n  readonly partNumber: number\n  /** Part bytes to upload. */\n  readonly data: BodyInit\n  /** Number of bytes in the part. */\n  readonly contentLength: number\n  /** SHA-1 hex digest of the part bytes. */\n  readonly contentSha1: string\n  /** Server-side encryption settings for this part. */\n  readonly serverSideEncryption?: EncryptionSetting | undefined\n}\n\n/**\n * Uploads one multipart part with fresh-URL retry.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param fileId - Large file to upload a part into.\n * @param options - Part upload parameters and retry settings.\n *\n * @returns The uploaded part response.\n */\nexport function uploadPartWithFreshUrl(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  fileId: LargeFileId,\n  options: UploadPartWithFreshUrlOptions,\n): Promise<UploadPartResponse> {\n  return withFreshUploadUrlRetry({\n    fileName: options.fileName,\n    partNumber: options.partNumber,\n    retry: options.retry,\n    signal: options.signal,\n    onUploadRetry: options.onUploadRetry,\n    retryResponseBodyFailures: options.retryResponseBodyFailures,\n    checkout: () => accountInfo.checkoutPartUploadUrl(fileId),\n    fetchFresh: () => fetchFreshPartUploadUrl(raw, accountInfo, fileId, options.signal),\n    returnEntry: (entry) => accountInfo.returnPartUploadUrl(fileId, entry),\n    evictEntry: (entry) => accountInfo.evictPartUploadUrl(fileId, entry),\n    upload: (entry) =>\n      raw.uploadPart(\n        entry.uploadUrl,\n        {\n          authorization: entry.authorizationToken,\n          partNumber: options.partNumber,\n          contentLength: options.contentLength,\n          contentSha1: options.contentSha1,\n          ...(options.serverSideEncryption !== undefined\n            ? { serverSideEncryption: options.serverSideEncryption }\n            : {}),\n        },\n        options.data,\n        {\n          ...(options.signal !== undefined ? { signal: options.signal } : {}),\n          ...(options.retry !== undefined ? { retry: options.retry } : {}),\n        },\n      ),\n  })\n}\n\n/**\n * Runs an upload operation with B2's documented retry flow: evict the failed\n * upload URL, back off, fetch a fresh upload URL, and retry there.\n *\n * For single-request file uploads, sending the POST again after a lost success\n * response can create a duplicate file version. Multipart retries re-send the\n * same part number instead. Response-body retry defaults are caller-specific:\n * single-request uploads keep them off by default, while multipart callers can\n * opt in with `retryResponseBodyFailures: true` when replaying the same part\n * number is acceptable.\n *\n * @param options - URL checkout, upload, eviction, and retry callbacks.\n *\n * @returns The successful upload result.\n */\nexport async function withFreshUploadUrlRetry<T>(options: FreshUrlRetryOptions<T>): Promise<T> {\n  const retryOptions = { ...DEFAULT_RETRY_OPTIONS, ...options.retry }\n\n  for (let attempt = 0; attempt <= retryOptions.maxRetries; attempt++) {\n    let uploadEntry: UploadUrlEntry | undefined\n    let uploadStarted = false\n\n    try {\n      options.signal?.throwIfAborted()\n      uploadEntry =\n        attempt === 0\n          ? (options.checkout() ?? (await options.fetchFresh()))\n          : await options.fetchFresh()\n\n      uploadStarted = true\n      const result = await options.upload(uploadEntry)\n      options.returnEntry(uploadEntry)\n      return result\n    } catch (err) {\n      const retryError = normalizeUploadRetryError(err, options)\n      if (uploadEntry !== undefined) {\n        if (isUploadRateLimitError(retryError)) {\n          options.returnEntry(uploadEntry)\n        } else {\n          options.evictEntry(uploadEntry)\n        }\n      }\n      if (options.signal?.aborted) {\n        throw err\n      }\n      if (isUploadRateLimitError(retryError) && uploadEntry !== undefined) {\n        throw retryError\n      }\n      if (\n        !isUploadRetryable(retryError, { ...options, uploadStarted }) ||\n        attempt === retryOptions.maxRetries\n      ) {\n        throw retryError\n      }\n\n      const retryAttempt = attempt + 1\n      const retryAfter = retryError instanceof B2Error ? retryError.retryAfter : undefined\n      const delayMs = computeBackoff(attempt, retryOptions, retryAfter)\n      notifyUploadRetry(options, {\n        fileName: options.fileName,\n        partNumber: options.partNumber,\n        attempt: retryAttempt,\n        maxRetries: retryOptions.maxRetries,\n        delayMs,\n        error: retryError,\n      })\n      await sleep(delayMs, options.signal)\n    }\n  }\n\n  // Unreachable at runtime: the loop returns on success or throws from the\n  // final failed attempt. This satisfies TypeScript's return-path analysis.\n  /* v8 ignore next -- defensive return-path guard. */\n  throw new NetworkError('Upload retry budget exhausted')\n}\n\nfunction notifyUploadRetry(options: UploadLayerRetryOptions, event: UploadRetryEvent): void {\n  try {\n    options.onUploadRetry?.(event)\n  } catch {\n    // Telemetry observers must not replace the underlying upload failure or\n    // prevent a retry that can recover with a fresh upload URL.\n  }\n}\n\nfunction isUploadRetryable(\n  err: unknown,\n  options: UploadLayerRetryOptions & {\n    readonly partNumber: number | null\n    readonly uploadStarted: boolean\n  },\n): err is B2Error | NetworkError {\n  if (err instanceof NetworkError) {\n    if (err.cause instanceof B2SsrfError) return false\n    if (!options.uploadStarted) return true\n    return options.retryResponseBodyFailures === true\n  }\n  if (err instanceof BadAuthTokenError) return true\n  if (isUploadUrlInvalidationError(err)) return true\n  return err instanceof B2Error && err.retryable\n}\n\nfunction isUploadRateLimitError(err: unknown): err is B2Error {\n  return err instanceof B2Error && err.status === 429\n}\n\nfunction normalizeUploadRetryError(err: unknown, options: UploadLayerRetryOptions): unknown {\n  if (err instanceof B2Error || err instanceof NetworkError) return err\n  if (err instanceof UploadResponseBodyError) {\n    if (!options.retryResponseBodyFailures) return err\n    return new NetworkError(err.message, err)\n  }\n  if (err instanceof DOMException && err.name === 'AbortError') return err\n  if (err instanceof TypeError || err instanceof SyntaxError || err instanceof DOMException) {\n    const message = err instanceof Error ? err.message : 'Upload response read failed'\n    return new NetworkError(message, err)\n  }\n  return err\n}\n\nfunction isUploadUrlInvalidationError(err: unknown): boolean {\n  if (err instanceof BadUploadUrlError) return true\n  return err instanceof BadRequestError && /upload url/i.test(err.message)\n}\n"],"mappings":"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"}

package/dist/upload/retry.d.cts

@@ -0,0 +1,127 @@
+import { AccountInfo, UploadUrlEntry } from '../auth/account-info.js';
+import { B2Error, NetworkError } from '../errors/index.js';
+import { RetryOptions } from '../http/retry.js';
+import { RawClient } from '../raw/index.js';
+import { EncryptionSetting } from '../types/encryption.js';
+import { BucketId, LargeFileId } from '../types/ids.js';
+import { UploadPartResponse } from '../types/upload.js';
+/** Event emitted before an upload is retried against a fresh upload URL. */
+export interface UploadRetryEvent {
+    /** File name being uploaded. */
+    readonly fileName: string;
+    /** Multipart part number, or `null` for a single-request file upload. */
+    readonly partNumber: number | null;
+    /** One-based retry attempt that is about to run. */
+    readonly attempt: number;
+    /** Maximum number of retry attempts allowed for this upload operation. */
+    readonly maxRetries: number;
+    /** Backoff delay in milliseconds before the fresh URL is fetched. */
+    readonly delayMs: number;
+    /** Classified error that triggered the fresh-URL retry. */
+    readonly error: B2Error | NetworkError;
+}
+/** Callback invoked before an upload retry fetches a fresh upload URL. */
+export type UploadRetryListener = (event: UploadRetryEvent) => void;
+/** Shared public options for upload-layer fresh-URL retries. */
+export interface UploadRetryOptions {
+    /** Retry settings shared with the main transport retry configuration. */
+    readonly retry?: Partial<RetryOptions> | undefined;
+    /** Callback invoked before a fresh-URL upload retry. */
+    readonly onUploadRetry?: UploadRetryListener | undefined;
+    /**
+     * Whether ambiguous failures after an upload POST should be retried,
+     * including response-body read failures and transport errors where B2 may
+     * have stored the payload before the success response was lost.
+     * Defaults to false. Set true only when duplicate versions or parts are
+     * acceptable.
+     */
+    readonly retryResponseBodyFailures?: boolean | undefined;
+}
+interface UploadLayerRetryOptions extends Omit<UploadRetryOptions, 'retryResponseBodyFailures'> {
+    readonly retryResponseBodyFailures: boolean;
+    /** Abort signal for cancelling upload attempts and retry backoff sleeps. */
+    readonly signal?: AbortSignal | undefined;
+}
+interface FreshUrlRetryOptions<T> extends UploadLayerRetryOptions {
+    readonly fileName: string;
+    readonly partNumber: number | null;
+    readonly checkout: () => UploadUrlEntry | null;
+    readonly fetchFresh: () => Promise<UploadUrlEntry>;
+    readonly returnEntry: (entry: UploadUrlEntry) => void;
+    readonly evictEntry: (entry: UploadUrlEntry) => void;
+    readonly upload: (entry: UploadUrlEntry) => Promise<T>;
+}
+/**
+ * Resolves the public default for `retryResponseBodyFailures`. Callers must
+ * opt into replaying ambiguous upload POST failures for every upload mode.
+ *
+ * @param value - Caller-provided override, if any.
+ *
+ * @returns The boolean value passed to the upload retry helper.
+ */
+export declare function resolveRetryResponseBodyFailures(value: boolean | undefined): boolean;
+/**
+ * Fetches a small-file upload URL, bypassing the pool.
+ *
+ * @param raw - Low-level B2 API client.
+ * @param accountInfo - Authorized account state.
+ * @param bucketId - Bucket to upload into.
+ * @param signal - Optional abort signal for the fresh URL request.
+ *
+ * @returns A fresh upload URL entry.
+ */
+export declare function fetchFreshUploadUrl(raw: RawClient, accountInfo: AccountInfo, bucketId: BucketId, signal?: AbortSignal): Promise<UploadUrlEntry>;
+/**
+ * Fetches a large-file part upload URL, bypassing the pool.
+ *
+ * @param raw - Low-level B2 API client.
+ * @param accountInfo - Authorized account state.
+ * @param fileId - Large file to upload a part into.
+ * @param signal - Optional abort signal for the fresh URL request.
+ *
+ * @returns A fresh part upload URL entry.
+ */
+export declare function fetchFreshPartUploadUrl(raw: RawClient, accountInfo: AccountInfo, fileId: LargeFileId, signal?: AbortSignal): Promise<UploadUrlEntry>;
+interface UploadPartWithFreshUrlOptions extends UploadLayerRetryOptions {
+    /** File name associated with the large-file upload. */
+    readonly fileName: string;
+    /** One-based part number. */
+    readonly partNumber: number;
+    /** Part bytes to upload. */
+    readonly data: BodyInit;
+    /** Number of bytes in the part. */
+    readonly contentLength: number;
+    /** SHA-1 hex digest of the part bytes. */
+    readonly contentSha1: string;
+    /** Server-side encryption settings for this part. */
+    readonly serverSideEncryption?: EncryptionSetting | undefined;
+}
+/**
+ * Uploads one multipart part with fresh-URL retry.
+ *
+ * @param raw - Low-level B2 API client.
+ * @param accountInfo - Authorized account state.
+ * @param fileId - Large file to upload a part into.
+ * @param options - Part upload parameters and retry settings.
+ *
+ * @returns The uploaded part response.
+ */
+export declare function uploadPartWithFreshUrl(raw: RawClient, accountInfo: AccountInfo, fileId: LargeFileId, options: UploadPartWithFreshUrlOptions): Promise<UploadPartResponse>;
+/**
+ * Runs an upload operation with B2's documented retry flow: evict the failed
+ * upload URL, back off, fetch a fresh upload URL, and retry there.
+ *
+ * For single-request file uploads, sending the POST again after a lost success
+ * response can create a duplicate file version. Multipart retries re-send the
+ * same part number instead. Response-body retry defaults are caller-specific:
+ * single-request uploads keep them off by default, while multipart callers can
+ * opt in with `retryResponseBodyFailures: true` when replaying the same part
+ * number is acceptable.
+ *
+ * @param options - URL checkout, upload, eviction, and retry callbacks.
+ *
+ * @returns The successful upload result.
+ */
+export declare function withFreshUploadUrlRetry<T>(options: FreshUrlRetryOptions<T>): Promise<T>;
+export {};
+//# sourceMappingURL=retry.d.ts.map

package/dist/upload/retry.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/upload/retry.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAC1E,OAAO,EACL,OAAO,EAKP,YAAY,EAEb,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAyC,KAAK,YAAY,EAAS,MAAM,kBAAkB,CAAA;AAClG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAE5D,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,CAAA;CACvC;AAED,0EAA0E;AAC1E,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAA;AAEnE,gEAAgE;AAChE,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,SAAS,CAAA;IAClD,wDAAwD;IACxD,QAAQ,CAAC,aAAa,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAA;IACxD;;;;;;OAMG;IACH,QAAQ,CAAC,yBAAyB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CACzD;AAED,UAAU,uBAAwB,SAAQ,IAAI,CAAC,kBAAkB,EAAE,2BAA2B,CAAC;IAC7F,QAAQ,CAAC,yBAAyB,EAAE,OAAO,CAAA;IAC3C,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;CAC1C;AAED,UAAU,oBAAoB,CAAC,CAAC,CAAE,SAAQ,uBAAuB;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,cAAc,GAAG,IAAI,CAAA;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAA;IAClD,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAA;IACrD,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAA;IACpD,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;CACvD;AAID;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAEpF;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,SAAS,EACd,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,QAAQ,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CAazB;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,SAAS,EACd,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,WAAW,EACnB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CAazB;AAED,UAAU,6BAA8B,SAAQ,uBAAuB;IACrE,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,6BAA6B;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,mCAAmC;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,0CAA0C;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAA;CAC9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,SAAS,EACd,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,kBAAkB,CAAC,CA+B7B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,CAAC,CAAC,EAAE,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA2D7F"}

package/dist/upload/retry.d.ts

@@ -0,0 +1,127 @@
+import { AccountInfo, UploadUrlEntry } from '../auth/account-info.js';
+import { B2Error, NetworkError } from '../errors/index.js';
+import { RetryOptions } from '../http/retry.js';
+import { RawClient } from '../raw/index.js';
+import { EncryptionSetting } from '../types/encryption.js';
+import { BucketId, LargeFileId } from '../types/ids.js';
+import { UploadPartResponse } from '../types/upload.js';
+/** Event emitted before an upload is retried against a fresh upload URL. */
+export interface UploadRetryEvent {
+    /** File name being uploaded. */
+    readonly fileName: string;
+    /** Multipart part number, or `null` for a single-request file upload. */
+    readonly partNumber: number | null;
+    /** One-based retry attempt that is about to run. */
+    readonly attempt: number;
+    /** Maximum number of retry attempts allowed for this upload operation. */
+    readonly maxRetries: number;
+    /** Backoff delay in milliseconds before the fresh URL is fetched. */
+    readonly delayMs: number;
+    /** Classified error that triggered the fresh-URL retry. */
+    readonly error: B2Error | NetworkError;
+}
+/** Callback invoked before an upload retry fetches a fresh upload URL. */
+export type UploadRetryListener = (event: UploadRetryEvent) => void;
+/** Shared public options for upload-layer fresh-URL retries. */
+export interface UploadRetryOptions {
+    /** Retry settings shared with the main transport retry configuration. */
+    readonly retry?: Partial<RetryOptions> | undefined;
+    /** Callback invoked before a fresh-URL upload retry. */
+    readonly onUploadRetry?: UploadRetryListener | undefined;
+    /**
+     * Whether ambiguous failures after an upload POST should be retried,
+     * including response-body read failures and transport errors where B2 may
+     * have stored the payload before the success response was lost.
+     * Defaults to false. Set true only when duplicate versions or parts are
+     * acceptable.
+     */
+    readonly retryResponseBodyFailures?: boolean | undefined;
+}
+interface UploadLayerRetryOptions extends Omit<UploadRetryOptions, 'retryResponseBodyFailures'> {
+    readonly retryResponseBodyFailures: boolean;
+    /** Abort signal for cancelling upload attempts and retry backoff sleeps. */
+    readonly signal?: AbortSignal | undefined;
+}
+interface FreshUrlRetryOptions<T> extends UploadLayerRetryOptions {
+    readonly fileName: string;
+    readonly partNumber: number | null;
+    readonly checkout: () => UploadUrlEntry | null;
+    readonly fetchFresh: () => Promise<UploadUrlEntry>;
+    readonly returnEntry: (entry: UploadUrlEntry) => void;
+    readonly evictEntry: (entry: UploadUrlEntry) => void;
+    readonly upload: (entry: UploadUrlEntry) => Promise<T>;
+}
+/**
+ * Resolves the public default for `retryResponseBodyFailures`. Callers must
+ * opt into replaying ambiguous upload POST failures for every upload mode.
+ *
+ * @param value - Caller-provided override, if any.
+ *
+ * @returns The boolean value passed to the upload retry helper.
+ */
+export declare function resolveRetryResponseBodyFailures(value: boolean | undefined): boolean;
+/**
+ * Fetches a small-file upload URL, bypassing the pool.
+ *
+ * @param raw - Low-level B2 API client.
+ * @param accountInfo - Authorized account state.
+ * @param bucketId - Bucket to upload into.
+ * @param signal - Optional abort signal for the fresh URL request.
+ *
+ * @returns A fresh upload URL entry.
+ */
+export declare function fetchFreshUploadUrl(raw: RawClient, accountInfo: AccountInfo, bucketId: BucketId, signal?: AbortSignal): Promise<UploadUrlEntry>;
+/**
+ * Fetches a large-file part upload URL, bypassing the pool.
+ *
+ * @param raw - Low-level B2 API client.
+ * @param accountInfo - Authorized account state.
+ * @param fileId - Large file to upload a part into.
+ * @param signal - Optional abort signal for the fresh URL request.
+ *
+ * @returns A fresh part upload URL entry.
+ */
+export declare function fetchFreshPartUploadUrl(raw: RawClient, accountInfo: AccountInfo, fileId: LargeFileId, signal?: AbortSignal): Promise<UploadUrlEntry>;
+interface UploadPartWithFreshUrlOptions extends UploadLayerRetryOptions {
+    /** File name associated with the large-file upload. */
+    readonly fileName: string;
+    /** One-based part number. */
+    readonly partNumber: number;
+    /** Part bytes to upload. */
+    readonly data: BodyInit;
+    /** Number of bytes in the part. */
+    readonly contentLength: number;
+    /** SHA-1 hex digest of the part bytes. */
+    readonly contentSha1: string;
+    /** Server-side encryption settings for this part. */
+    readonly serverSideEncryption?: EncryptionSetting | undefined;
+}
+/**
+ * Uploads one multipart part with fresh-URL retry.
+ *
+ * @param raw - Low-level B2 API client.
+ * @param accountInfo - Authorized account state.
+ * @param fileId - Large file to upload a part into.
+ * @param options - Part upload parameters and retry settings.
+ *
+ * @returns The uploaded part response.
+ */
+export declare function uploadPartWithFreshUrl(raw: RawClient, accountInfo: AccountInfo, fileId: LargeFileId, options: UploadPartWithFreshUrlOptions): Promise<UploadPartResponse>;
+/**
+ * Runs an upload operation with B2's documented retry flow: evict the failed
+ * upload URL, back off, fetch a fresh upload URL, and retry there.
+ *
+ * For single-request file uploads, sending the POST again after a lost success
+ * response can create a duplicate file version. Multipart retries re-send the
+ * same part number instead. Response-body retry defaults are caller-specific:
+ * single-request uploads keep them off by default, while multipart callers can
+ * opt in with `retryResponseBodyFailures: true` when replaying the same part
+ * number is acceptable.
+ *
+ * @param options - URL checkout, upload, eviction, and retry callbacks.
+ *
+ * @returns The successful upload result.
+ */
+export declare function withFreshUploadUrlRetry<T>(options: FreshUrlRetryOptions<T>): Promise<T>;
+export {};
+//# sourceMappingURL=retry.d.ts.map

package/dist/upload/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/upload/retry.js"],"names":[],"mappings":"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"}

package/dist/upload/retry.js

@@ -0,0 +1,182 @@
+import { B2Error, B2SsrfError, BadAuthTokenError, BadRequestError, BadUploadUrlError, NetworkError, UploadResponseBodyError } from "../errors/index.js";
+import { DEFAULT_RETRY_OPTIONS, computeBackoff, sleep } from "../http/retry.js";
+//#region src/upload/retry.ts
+var freshUrlRetryOverride = { maxRetries: 0 };
+/**
+* Resolves the public default for `retryResponseBodyFailures`. Callers must
+* opt into replaying ambiguous upload POST failures for every upload mode.
+*
+* @param value - Caller-provided override, if any.
+*
+* @returns The boolean value passed to the upload retry helper.
+*/
+function resolveRetryResponseBodyFailures(value) {
+	return value ?? false;
+}
+/**
+* Fetches a small-file upload URL, bypassing the pool.
+*
+* @param raw - Low-level B2 API client.
+* @param accountInfo - Authorized account state.
+* @param bucketId - Bucket to upload into.
+* @param signal - Optional abort signal for the fresh URL request.
+*
+* @returns A fresh upload URL entry.
+*/
+async function fetchFreshUploadUrl(raw, accountInfo, bucketId, signal) {
+	const resp = await raw.getUploadUrl(accountInfo.getApiUrl(), accountInfo.getAuthToken(), { bucketId }, {
+		...signal !== void 0 ? { signal } : {},
+		retry: freshUrlRetryOverride
+	});
+	return {
+		uploadUrl: resp.uploadUrl,
+		authorizationToken: resp.authorizationToken
+	};
+}
+/**
+* Fetches a large-file part upload URL, bypassing the pool.
+*
+* @param raw - Low-level B2 API client.
+* @param accountInfo - Authorized account state.
+* @param fileId - Large file to upload a part into.
+* @param signal - Optional abort signal for the fresh URL request.
+*
+* @returns A fresh part upload URL entry.
+*/
+async function fetchFreshPartUploadUrl(raw, accountInfo, fileId, signal) {
+	const resp = await raw.getUploadPartUrl(accountInfo.getApiUrl(), accountInfo.getAuthToken(), { fileId }, {
+		...signal !== void 0 ? { signal } : {},
+		retry: freshUrlRetryOverride
+	});
+	return {
+		uploadUrl: resp.uploadUrl,
+		authorizationToken: resp.authorizationToken
+	};
+}
+/**
+* Uploads one multipart part with fresh-URL retry.
+*
+* @param raw - Low-level B2 API client.
+* @param accountInfo - Authorized account state.
+* @param fileId - Large file to upload a part into.
+* @param options - Part upload parameters and retry settings.
+*
+* @returns The uploaded part response.
+*/
+function uploadPartWithFreshUrl(raw, accountInfo, fileId, options) {
+	return withFreshUploadUrlRetry({
+		fileName: options.fileName,
+		partNumber: options.partNumber,
+		retry: options.retry,
+		signal: options.signal,
+		onUploadRetry: options.onUploadRetry,
+		retryResponseBodyFailures: options.retryResponseBodyFailures,
+		checkout: () => accountInfo.checkoutPartUploadUrl(fileId),
+		fetchFresh: () => fetchFreshPartUploadUrl(raw, accountInfo, fileId, options.signal),
+		returnEntry: (entry) => accountInfo.returnPartUploadUrl(fileId, entry),
+		evictEntry: (entry) => accountInfo.evictPartUploadUrl(fileId, entry),
+		upload: (entry) => raw.uploadPart(entry.uploadUrl, {
+			authorization: entry.authorizationToken,
+			partNumber: options.partNumber,
+			contentLength: options.contentLength,
+			contentSha1: options.contentSha1,
+			...options.serverSideEncryption !== void 0 ? { serverSideEncryption: options.serverSideEncryption } : {}
+		}, options.data, {
+			...options.signal !== void 0 ? { signal: options.signal } : {},
+			...options.retry !== void 0 ? { retry: options.retry } : {}
+		})
+	});
+}
+/**
+* Runs an upload operation with B2's documented retry flow: evict the failed
+* upload URL, back off, fetch a fresh upload URL, and retry there.
+*
+* For single-request file uploads, sending the POST again after a lost success
+* response can create a duplicate file version. Multipart retries re-send the
+* same part number instead. Response-body retry defaults are caller-specific:
+* single-request uploads keep them off by default, while multipart callers can
+* opt in with `retryResponseBodyFailures: true` when replaying the same part
+* number is acceptable.
+*
+* @param options - URL checkout, upload, eviction, and retry callbacks.
+*
+* @returns The successful upload result.
+*/
+async function withFreshUploadUrlRetry(options) {
+	const retryOptions = {
+		...DEFAULT_RETRY_OPTIONS,
+		...options.retry
+	};
+	for (let attempt = 0; attempt <= retryOptions.maxRetries; attempt++) {
+		let uploadEntry;
+		let uploadStarted = false;
+		try {
+			options.signal?.throwIfAborted();
+			uploadEntry = attempt === 0 ? options.checkout() ?? await options.fetchFresh() : await options.fetchFresh();
+			uploadStarted = true;
+			const result = await options.upload(uploadEntry);
+			options.returnEntry(uploadEntry);
+			return result;
+		} catch (err) {
+			const retryError = normalizeUploadRetryError(err, options);
+			if (uploadEntry !== void 0) if (isUploadRateLimitError(retryError)) options.returnEntry(uploadEntry);
+			else options.evictEntry(uploadEntry);
+			if (options.signal?.aborted) throw err;
+			if (isUploadRateLimitError(retryError) && uploadEntry !== void 0) throw retryError;
+			if (!isUploadRetryable(retryError, {
+				...options,
+				uploadStarted
+			}) || attempt === retryOptions.maxRetries) throw retryError;
+			const retryAttempt = attempt + 1;
+			const retryAfter = retryError instanceof B2Error ? retryError.retryAfter : void 0;
+			const delayMs = computeBackoff(attempt, retryOptions, retryAfter);
+			notifyUploadRetry(options, {
+				fileName: options.fileName,
+				partNumber: options.partNumber,
+				attempt: retryAttempt,
+				maxRetries: retryOptions.maxRetries,
+				delayMs,
+				error: retryError
+			});
+			await sleep(delayMs, options.signal);
+		}
+	}
+	/* v8 ignore next -- defensive return-path guard. */
+	throw new NetworkError("Upload retry budget exhausted");
+}
+function notifyUploadRetry(options, event) {
+	try {
+		options.onUploadRetry?.(event);
+	} catch {}
+}
+function isUploadRetryable(err, options) {
+	if (err instanceof NetworkError) {
+		if (err.cause instanceof B2SsrfError) return false;
+		if (!options.uploadStarted) return true;
+		return options.retryResponseBodyFailures === true;
+	}
+	if (err instanceof BadAuthTokenError) return true;
+	if (isUploadUrlInvalidationError(err)) return true;
+	return err instanceof B2Error && err.retryable;
+}
+function isUploadRateLimitError(err) {
+	return err instanceof B2Error && err.status === 429;
+}
+function normalizeUploadRetryError(err, options) {
+	if (err instanceof B2Error || err instanceof NetworkError) return err;
+	if (err instanceof UploadResponseBodyError) {
+		if (!options.retryResponseBodyFailures) return err;
+		return new NetworkError(err.message, err);
+	}
+	if (err instanceof DOMException && err.name === "AbortError") return err;
+	if (err instanceof TypeError || err instanceof SyntaxError || err instanceof DOMException) return new NetworkError(err instanceof Error ? err.message : "Upload response read failed", err);
+	return err;
+}
+function isUploadUrlInvalidationError(err) {
+	if (err instanceof BadUploadUrlError) return true;
+	return err instanceof BadRequestError && /upload url/i.test(err.message);
+}
+//#endregion
+export { fetchFreshPartUploadUrl, fetchFreshUploadUrl, resolveRetryResponseBodyFailures, uploadPartWithFreshUrl, withFreshUploadUrlRetry };
+
+//# sourceMappingURL=retry.js.map