@backblaze-labs/b2-sdk 0.2.0 → 0.3.0

package/dist/download/checksum.js.map

@@ -1 +1 @@
-{"version":3,"file":"checksum.js","names":[],"sources":["../../src/download/checksum.ts"],"sourcesContent":["/**\n * Client-side checksum helpers for download streams.\n *\n * B2 sends `X-Bz-Content-Sha1` on download responses when a whole-file\n * checksum is available. These helpers verify streamed bytes against that\n * header without buffering the full response in memory.\n *\n * @packageDocumentation\n */\n\nimport { ChecksumMismatchError } from '../errors/index.ts'\nimport { IncrementalSha1 } from '../streams/hash.ts'\nimport { isVerifiableSha1 } from '../util/sha1.ts'\n\n/**\n * Builds the typed error used when downloaded bytes fail SHA-1 verification.\n *\n * @param expectedSha1 - SHA-1 digest advertised by the download response.\n * @param actualSha1 - SHA-1 digest computed from the downloaded bytes.\n *\n * @returns A typed checksum mismatch error.\n */\nfunction createDownloadChecksumMismatchError(\n  expectedSha1: string,\n  actualSha1: string,\n): ChecksumMismatchError {\n  const expected = expectedSha1.toLowerCase()\n  const actual = actualSha1.toLowerCase()\n  return new ChecksumMismatchError({\n    status: 400,\n    code: 'bad_sha1_checksum',\n    message: `Downloaded content SHA-1 mismatch: expected ${expected}, got ${actual}`,\n  })\n}\n\n/**\n * Throws when a computed download SHA-1 does not match the expected value.\n *\n * @param expectedSha1 - SHA-1 digest advertised by the download response.\n * @param actualSha1 - SHA-1 digest computed from the downloaded bytes.\n *\n * @throws ChecksumMismatchError when the two digests differ.\n */\nexport function assertDownloadSha1(expectedSha1: string, actualSha1: string): void {\n  if (actualSha1.toLowerCase() !== expectedSha1.toLowerCase()) {\n    throw createDownloadChecksumMismatchError(expectedSha1, actualSha1)\n  }\n}\n\n/**\n * Throws when two range responses disagree about the expected whole-file SHA-1.\n *\n * @param expectedSha1 - The first range's verifiable SHA-1, or null when unavailable.\n * @param actualSha1 - The current range's verifiable SHA-1, or null when unavailable.\n *\n * @throws ChecksumMismatchError when the two header states differ.\n */\nexport function assertDownloadSha1HeaderAgreement(\n  expectedSha1: string | null,\n  actualSha1: string | null,\n): void {\n  if (expectedSha1 === actualSha1) return\n  const expected = formatSha1ForMessage(expectedSha1)\n  const actual = formatSha1ForMessage(actualSha1)\n  throw new ChecksumMismatchError({\n    status: 400,\n    code: 'bad_sha1_checksum',\n    message: `Downloaded content SHA-1 header mismatch: expected ${expected}, got ${actual}`,\n  })\n}\n\n/**\n * Wraps a download stream with whole-body SHA-1 verification.\n *\n * If B2 did not provide a verifiable whole-file SHA-1 (for example,\n * multipart-finished files report `none`), the original stream is returned.\n *\n * @param body - Download response body.\n * @param expectedSha1 - Normalized SHA-1 header value, or null when unavailable.\n *\n * @returns A stream that emits the same bytes and errors on checksum mismatch.\n */\nexport function verifyDownloadStream(\n  body: ReadableStream<Uint8Array>,\n  expectedSha1: string | null,\n): ReadableStream<Uint8Array> {\n  if (!isVerifiableSha1(expectedSha1)) return body\n\n  const sha1 = new IncrementalSha1()\n  const transform = new TransformStream<Uint8Array, Uint8Array>({\n    async transform(chunk, controller) {\n      await sha1.update(chunk)\n      controller.enqueue(chunk)\n    },\n    async flush() {\n      assertDownloadSha1(expectedSha1, await sha1.digest())\n    },\n  })\n  return body.pipeThrough(transform)\n}\n\nfunction formatSha1ForMessage(sha1: string | null): string {\n  return sha1 === null ? 'missing or unverifiable' : sha1.toLowerCase()\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAsBA,SAAS,oCACP,cACA,YACuB;CAGvB,OAAO,IAAI,sBAAsB;EAC/B,QAAQ;EACR,MAAM;EACN,SAAS,+CALM,aAAa,YAK4B,EAAS,QAJpD,WAAW,YAIiD;CAC3E,CAAC;AACH;;;;;;;;;AAUA,SAAgB,mBAAmB,cAAsB,YAA0B;CACjF,IAAI,WAAW,YAAY,MAAM,aAAa,YAAY,GACxD,MAAM,oCAAoC,cAAc,UAAU;AAEtE;;;;;;;;;AAUA,SAAgB,kCACd,cACA,YACM;CACN,IAAI,iBAAiB,YAAY;CAGjC,MAAM,IAAI,sBAAsB;EAC9B,QAAQ;EACR,MAAM;EACN,SAAS,sDALM,qBAAqB,YAK2B,EAAS,QAJ3D,qBAAqB,UAI8C;CAClF,CAAC;AACH;;;;;;;;;;;;AAaA,SAAgB,qBACd,MACA,cAC4B;CAC5B,IAAI,CAAC,iBAAiB,YAAY,GAAG,OAAO;CAE5C,MAAM,OAAO,IAAI,gBAAgB;CACjC,MAAM,YAAY,IAAI,gBAAwC;EAC5D,MAAM,UAAU,OAAO,YAAY;GACjC,MAAM,KAAK,OAAO,KAAK;GACvB,WAAW,QAAQ,KAAK;EAC1B;EACA,MAAM,QAAQ;GACZ,mBAAmB,cAAc,MAAM,KAAK,OAAO,CAAC;EACtD;CACF,CAAC;CACD,OAAO,KAAK,YAAY,SAAS;AACnC;AAEA,SAAS,qBAAqB,MAA6B;CACzD,OAAO,SAAS,OAAO,4BAA4B,KAAK,YAAY;AACtE"}
+{"version":3,"file":"checksum.js","names":[],"sources":["../../src/download/checksum.ts"],"sourcesContent":["/**\n * Client-side checksum helpers for download streams.\n *\n * B2 sends `X-Bz-Content-Sha1` on download responses when a whole-file\n * checksum is available. These helpers verify streamed bytes against that\n * header without buffering the full response in memory.\n *\n * @packageDocumentation\n */\n\nimport { ChecksumMismatchError } from '../errors/index.ts'\nimport { IncrementalSha1 } from '../streams/hash.ts'\nimport { isVerifiableSha1 } from '../util/sha1.ts'\n\n/**\n * Builds the typed error used when downloaded bytes fail SHA-1 verification.\n *\n * @param expectedSha1 - SHA-1 digest advertised by the download response.\n * @param actualSha1 - SHA-1 digest computed from the downloaded bytes.\n *\n * @returns A typed checksum mismatch error.\n */\nfunction createDownloadChecksumMismatchError(\n  expectedSha1: string,\n  actualSha1: string,\n): ChecksumMismatchError {\n  const expected = expectedSha1.toLowerCase()\n  const actual = actualSha1.toLowerCase()\n  return new ChecksumMismatchError({\n    status: 400,\n    code: 'bad_sha1_checksum',\n    message: `Downloaded content SHA-1 mismatch: expected ${expected}, got ${actual}`,\n  })\n}\n\n/**\n * Throws when a computed download SHA-1 does not match the expected value.\n *\n * @param expectedSha1 - SHA-1 digest advertised by the download response.\n * @param actualSha1 - SHA-1 digest computed from the downloaded bytes.\n *\n * @throws ChecksumMismatchError when the two digests differ.\n */\nexport function assertDownloadSha1(expectedSha1: string, actualSha1: string): void {\n  if (actualSha1.toLowerCase() !== expectedSha1.toLowerCase()) {\n    throw createDownloadChecksumMismatchError(expectedSha1, actualSha1)\n  }\n}\n\n/**\n * Throws when two range responses disagree about the expected whole-file SHA-1.\n *\n * @param expectedSha1 - The first range's verifiable SHA-1, or null when unavailable.\n * @param actualSha1 - The current range's verifiable SHA-1, or null when unavailable.\n *\n * @throws ChecksumMismatchError when the two header states differ.\n */\nexport function assertDownloadSha1HeaderAgreement(\n  expectedSha1: string | null,\n  actualSha1: string | null,\n): void {\n  if (expectedSha1 === actualSha1) return\n  const expected = formatSha1ForMessage(expectedSha1)\n  const actual = formatSha1ForMessage(actualSha1)\n  throw new ChecksumMismatchError({\n    status: 400,\n    code: 'bad_sha1_checksum',\n    message: `Downloaded content SHA-1 header mismatch: expected ${expected}, got ${actual}`,\n  })\n}\n\n/**\n * Wraps a download stream with whole-body SHA-1 verification.\n *\n * If B2 did not provide a verifiable whole-file SHA-1 (for example,\n * multipart-finished files report `none`), the original stream is returned.\n *\n * @param body - Download response body.\n * @param expectedSha1 - Normalized SHA-1 header value, or null when unavailable.\n *\n * @returns A stream that emits the same bytes and errors on checksum mismatch.\n */\nexport function verifyDownloadStream(\n  body: ReadableStream<Uint8Array>,\n  expectedSha1: string | null,\n): ReadableStream<Uint8Array> {\n  if (!isVerifiableSha1(expectedSha1)) return body\n\n  const sha1 = new IncrementalSha1()\n  const transform = new TransformStream<Uint8Array, Uint8Array>({\n    async transform(chunk, controller) {\n      await sha1.update(chunk)\n      controller.enqueue(chunk)\n    },\n    async flush() {\n      assertDownloadSha1(expectedSha1, await sha1.digest())\n    },\n  })\n  return body.pipeThrough(transform)\n}\n\nfunction formatSha1ForMessage(sha1: string | null): string {\n  return sha1 === null ? 'missing or unverifiable' : sha1.toLowerCase()\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAsBA,SAAS,oCACP,cACA,YACuB;CACvB,MAAM,WAAW,aAAa,YAAY;CAC1C,MAAM,SAAS,WAAW,YAAY;CACtC,OAAO,IAAI,sBAAsB;EAC/B,QAAQ;EACR,MAAM;EACN,SAAS,+CAA+C,SAAS,QAAQ;CAC3E,CAAC;AACH;;;;;;;;;AAUA,SAAgB,mBAAmB,cAAsB,YAA0B;CACjF,IAAI,WAAW,YAAY,MAAM,aAAa,YAAY,GACxD,MAAM,oCAAoC,cAAc,UAAU;AAEtE;;;;;;;;;AAUA,SAAgB,kCACd,cACA,YACM;CACN,IAAI,iBAAiB,YAAY;CACjC,MAAM,WAAW,qBAAqB,YAAY;CAClD,MAAM,SAAS,qBAAqB,UAAU;CAC9C,MAAM,IAAI,sBAAsB;EAC9B,QAAQ;EACR,MAAM;EACN,SAAS,sDAAsD,SAAS,QAAQ;CAClF,CAAC;AACH;;;;;;;;;;;;AAaA,SAAgB,qBACd,MACA,cAC4B;CAC5B,IAAI,CAAC,iBAAiB,YAAY,GAAG,OAAO;CAE5C,MAAM,OAAO,IAAI,gBAAgB;CACjC,MAAM,YAAY,IAAI,gBAAwC;EAC5D,MAAM,UAAU,OAAO,YAAY;GACjC,MAAM,KAAK,OAAO,KAAK;GACvB,WAAW,QAAQ,KAAK;EAC1B;EACA,MAAM,QAAQ;GACZ,mBAAmB,cAAc,MAAM,KAAK,OAAO,CAAC;EACtD;CACF,CAAC;CACD,OAAO,KAAK,YAAY,SAAS;AACnC;AAEA,SAAS,qBAAqB,MAA6B;CACzD,OAAO,SAAS,OAAO,4BAA4B,KAAK,YAAY;AACtE"}

package/dist/download/parallel.cjs

@@ -1,6 +1,8 @@
 const require_errors_index = require("../errors/index.cjs");
+require("../util/defaults.cjs");
 const require_plan_ranges = require("../util/plan-ranges.cjs");
 const require_text_codec = require("../util/text-codec.cjs");
+const require_encryption = require("../types/encryption.cjs");
 const require_normalize = require("../util/normalize.cjs");
 const require_hash = require("../streams/hash.cjs");
 const require_sha1 = require("../util/sha1.cjs");
@@ -31,14 +33,26 @@ const require_collect = require("../streams/collect.cjs");
 * @returns A `ReadableStream` that yields file bytes in order.
 */
 function createParallelDownloadStream(raw, accountInfo, options) {
-	const rangeSize = options.rangeSize ?? 10 * 1024 * 1024;
+	const rangeSize = options.rangeSize ?? 10485760;
 	const concurrency = options.concurrency ?? 4;
 	const totalSize = options.totalSize;
+	const serverSideEncryption = options.serverSideEncryption !== void 0 ? require_encryption.redactSseCKeyMaterial(options.serverSideEncryption, { label: "SseCDownloadKey" }) : void 0;
 	const retryOptions = {
 		...require_retry.DEFAULT_RETRY_OPTIONS,
 		maxRetries: options.maxRetries ?? 0
 	};
-	const abort = options.signal;
+	const internalAbort = new AbortController();
+	const abort = internalAbort.signal;
+	let removeCallerAbortListener;
+	if (options.signal !== void 0) {
+		if (options.signal.aborted) internalAbort.abort(options.signal.reason);
+		else {
+			const callerSignal = options.signal;
+			const abortFromCaller = () => internalAbort.abort(callerSignal.reason);
+			callerSignal.addEventListener("abort", abortFromCaller, { once: true });
+			removeCallerAbortListener = () => callerSignal.removeEventListener("abort", abortFromCaller);
+		}
+	}
 	const ranges = require_plan_ranges.planRanges(totalSize, rangeSize);
 	const windowSize = concurrency * 2;
 	const inflight = /* @__PURE__ */ new Map();
@@ -48,6 +62,13 @@ function createParallelDownloadStream(raw, accountInfo, options) {
 	let nextToEmit = 0;
 	let expectedSha1;
 	let firstError = null;
+	function abortInflight(reason) {
+		if (!abort.aborted) internalAbort.abort(reason);
+	}
+	function cleanupCallerAbortListener() {
+		removeCallerAbortListener?.();
+		removeCallerAbortListener = void 0;
+	}
 	function scheduleNext() {
 		while (firstError === null && abort?.aborted !== true && nextToSchedule < ranges.length && inflight.size + buffer.size < windowSize) {
 			const range = ranges[nextToSchedule];
@@ -56,10 +77,23 @@ function createParallelDownloadStream(raw, accountInfo, options) {
 			nextToSchedule++;
 			const task = (async () => {
 				try {
-					const result = await fetchRangeWithRetry(raw, accountInfo, options.fileId, range.start, range.end, totalSize, retryOptions, abort);
+					const result = await fetchRangeWithRetry({
+						raw,
+						accountInfo,
+						fileId: options.fileId,
+						start: range.start,
+						end: range.end,
+						totalSize,
+						serverSideEncryption,
+						retryOptions,
+						signal: abort
+					});
 					buffer.set(idx, result);
 				} catch (err) {
-					if (firstError === null) firstError = err;
+					if (firstError === null) {
+						firstError = err;
+						abortInflight(err);
+					}
 				} finally {
 					inflight.delete(idx);
 				}
@@ -73,6 +107,7 @@ function createParallelDownloadStream(raw, accountInfo, options) {
 				abort?.throwIfAborted();
 				scheduleNext();
 			} catch (err) {
+				cleanupCallerAbortListener();
 				controller.error(err);
 			}
 		},
@@ -82,6 +117,7 @@ function createParallelDownloadStream(raw, accountInfo, options) {
 					abort?.throwIfAborted();
 					if (firstError !== null) throw firstError;
 					if (inflight.size === 0) {
+						cleanupCallerAbortListener();
 						controller.close();
 						return;
 					}
@@ -103,41 +139,42 @@ function createParallelDownloadStream(raw, accountInfo, options) {
 				scheduleNext();
 				if (nextToEmit >= ranges.length && buffer.size === 0 && inflight.size === 0 && firstError === null) {
 					if (expectedSha1 !== void 0 && expectedSha1 !== null && assembledSha1 !== null) require_checksum.assertDownloadSha1(expectedSha1, await assembledSha1.digest());
+					cleanupCallerAbortListener();
 					controller.close();
 				}
 			} catch (err) {
+				abortInflight(err);
+				cleanupCallerAbortListener();
 				controller.error(err);
 			}
 		},
-		cancel() {
+		cancel(reason) {
+			abortInflight(reason);
+			cleanupCallerAbortListener();
 			buffer.clear();
 		}
 	});
 }
 /**
 * Fetches a single byte range with bounded retry on transient failures.
-* @param raw - Low-level B2 API client.
-* @param accountInfo - Authorized account state.
-* @param fileId - ID of the file being downloaded.
-* @param start - Inclusive byte offset where the range begins.
-* @param end - Inclusive byte offset where the range ends.
-* @param totalSize - Expected complete file size.
-* @param retryOptions - Retry settings controlling attempts and backoff.
-* @param signal - Optional abort signal that cancels the range and any pending retry.
+* @param params - Range request parameters, retry settings, and cancellation.
 *
 * @returns The range's bytes, or throws after exhausting all retry attempts.
 */
-async function fetchRangeWithRetry(raw, accountInfo, fileId, start, end, totalSize, retryOptions, signal) {
+async function fetchRangeWithRetry(params) {
+	const { raw, accountInfo, fileId, start, end, totalSize, serverSideEncryption, retryOptions, signal } = params;
 	let lastError;
 	for (let attempt = 0; attempt <= retryOptions.maxRetries; attempt++) {
 		if (attempt > 0) {
 			const retryAfter = lastError instanceof require_errors_index.B2Error && lastError.retryAfter !== void 0 ? lastError.retryAfter : void 0;
-			await require_retry.sleep(require_retry.computeBackoff(attempt - 1, retryOptions, retryAfter), signal);
+			const delay = require_retry.computeBackoff(attempt - 1, retryOptions, retryAfter);
+			await require_retry.sleep(delay, signal);
 		}
 		try {
 			signal?.throwIfAborted();
 			const resp = await raw.downloadFileById(accountInfo.getDownloadUrl(), accountInfo.getAuthToken(), fileId, {
 				range: require_plan_ranges.byteRangeHeader(start, end),
+				...serverSideEncryption !== void 0 ? { serverSideEncryption } : {},
 				...signal !== void 0 ? { signal } : {}
 			});
 			if (resp.status < 200 || resp.status >= 300) throw await classifyDownloadResponseError(resp);

package/dist/download/parallel.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"parallel.cjs","names":[],"sources":["../../src/download/parallel.ts"],"sourcesContent":["import type { AccountInfo } from '../auth/account-info.ts'\nimport { B2Error, classifyError, NetworkError } from '../errors/index.ts'\nimport { computeBackoff, DEFAULT_RETRY_OPTIONS, type RetryOptions, sleep } from '../http/retry.ts'\nimport type { RawClient } from '../raw/index.ts'\nimport { collectStream } from '../streams/collect.ts'\nimport { IncrementalSha1 } from '../streams/hash.ts'\nimport type { B2ErrorResponse } from '../types/errors.ts'\nimport type { FileId } from '../types/ids.ts'\nimport { DEFAULT_TRANSFER_CONCURRENCY } from '../util/defaults.ts'\nimport { normalizeSha1 } from '../util/normalize.ts'\nimport { byteRangeHeader, planRanges } from '../util/plan-ranges.ts'\nimport { normalizeVerifiableSha1 } from '../util/sha1.ts'\nimport { utf8Decoder } from '../util/text-codec.ts'\nimport { assertDownloadSha1, assertDownloadSha1HeaderAgreement } from './checksum.ts'\n\n/** Options for downloading a file using concurrent byte-range requests. */\nexport interface ParallelDownloadOptions {\n  /** ID of the file to download. */\n  readonly fileId: FileId\n  /** Total file size in bytes (must be known in advance). */\n  readonly totalSize: number\n  /** Size of each ranged chunk in bytes. Defaults to 10 MB. */\n  readonly rangeSize?: number\n  /** Maximum number of chunks fetched in parallel. Defaults to 4. */\n  readonly concurrency?: number\n  /**\n   * Extra retry attempts per range on transient failures. Defaults to 0 because\n   * `B2Client` already applies `RetryTransport`; set this only when supplying a\n   * raw client that does not already retry transport failures.\n   */\n  readonly maxRetries?: number\n  /** Signal to abort the download. */\n  readonly signal?: AbortSignal\n}\n\ninterface RangeDownloadResult {\n  readonly data: Uint8Array\n  readonly contentSha1: string | null\n}\n\n/**\n * Creates a readable stream that downloads a file using parallel byte-range requests.\n *\n * The file is split into fixed-size ranges fetched in a **sliding\n * window** keyed off the consumer's read pace. The window size is\n * `concurrency * 2`: up to `concurrency` ranges are in flight at once,\n * plus up to `concurrency` completed-but-not-yet-emitted ranges buffered\n * ahead of the read head. New fetches kick off only when the consumer\n * reads a chunk, so a slow downstream pipe (e.g. a saturated network\n * sink or a `pipeTo` consumer that drains slowly) backpressures into\n * the SDK and bounds peak memory to `(concurrency * 2) * rangeSize`.\n *\n * The previous eager implementation scheduled every range into\n * `Promise.all` up front; a slow head-of-line range could hold the\n * entire file in memory while later ranges finished and waited.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param options - Parallel download parameters (file ID, size, concurrency).\n *\n * @returns A `ReadableStream` that yields file bytes in order.\n */\nexport function createParallelDownloadStream(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  options: ParallelDownloadOptions,\n): ReadableStream<Uint8Array> {\n  const rangeSize = options.rangeSize ?? 10 * 1024 * 1024\n  const concurrency = options.concurrency ?? DEFAULT_TRANSFER_CONCURRENCY\n  const totalSize = options.totalSize\n  // The high-level B2Client already wraps the raw transport in RetryTransport.\n  // Keep the parallel-download outer retry disabled by default so each range\n  // has one retry budget unless callers explicitly opt into an extra raw-client\n  // retry layer.\n  const retryOptions = {\n    ...DEFAULT_RETRY_OPTIONS,\n    maxRetries: options.maxRetries ?? 0,\n  }\n  const abort = options.signal\n\n  const ranges = planRanges(totalSize, rangeSize)\n\n  // `inflight` holds currently-fetching range promises; `buffer` holds\n  // completed ranges waiting for their slot in the emit order. Total\n  // scheduled-but-not-emitted = inflight.size + buffer.size is capped\n  // at `windowSize`, so peak memory is bounded regardless of any\n  // single range's latency.\n  const windowSize = concurrency * 2\n  const inflight = new Map<number, Promise<void>>()\n  const buffer = new Map<number, RangeDownloadResult>()\n  let assembledSha1: IncrementalSha1 | null = null\n  let nextToSchedule = 0\n  let nextToEmit = 0\n  let expectedSha1: string | null | undefined\n  let firstError: unknown = null\n\n  function scheduleNext(): void {\n    while (\n      firstError === null &&\n      // Honour abort here so a completed range that triggers a top-up\n      // doesn't queue one final fetch after the caller aborted. Without\n      // this gate, one extra range request fires post-abort before the\n      // `pull()` loop notices.\n      abort?.aborted !== true &&\n      nextToSchedule < ranges.length &&\n      inflight.size + buffer.size < windowSize\n    ) {\n      const range = ranges[nextToSchedule]\n      if (range === undefined) break\n      const idx = nextToSchedule\n      nextToSchedule++\n      const task = (async () => {\n        try {\n          const result = await fetchRangeWithRetry(\n            raw,\n            accountInfo,\n            options.fileId,\n            range.start,\n            range.end,\n            totalSize,\n            retryOptions,\n            abort,\n          )\n          buffer.set(idx, result)\n        } catch (err) {\n          if (firstError === null) firstError = err\n        } finally {\n          inflight.delete(idx)\n        }\n      })()\n      inflight.set(idx, task)\n    }\n  }\n\n  return new ReadableStream<Uint8Array>({\n    start(controller) {\n      // Pre-warm: kick off the initial window so the first `pull` has\n      // something to await. An already-aborted signal surfaces as a\n      // stream error rather than a synchronous throw, matching the\n      // contract callers had with the previous eager implementation.\n      try {\n        abort?.throwIfAborted()\n        scheduleNext()\n      } catch (err) {\n        controller.error(err)\n      }\n    },\n    async pull(controller) {\n      try {\n        // Wait until the next in-order chunk is available.\n        while (!buffer.has(nextToEmit)) {\n          abort?.throwIfAborted()\n          if (firstError !== null) throw firstError\n          // Zero-byte downloads have no planned ranges and close here. For\n          // non-empty downloads, this guard prevents a future refactor from\n          // stalling the stream if it leaves both maps empty mid-stream.\n          if (inflight.size === 0) {\n            controller.close()\n            return\n          }\n          await Promise.race(inflight.values())\n        }\n\n        const result = buffer.get(nextToEmit)\n        if (result !== undefined) {\n          buffer.delete(nextToEmit)\n          nextToEmit++\n          const rangeSha1 = normalizeVerifiableSha1(result.contentSha1)\n          if (expectedSha1 === undefined) {\n            expectedSha1 = rangeSha1\n          } else {\n            // B2 range responses should agree on the same whole-file SHA-1;\n            // any value or presence change makes verification untrustworthy.\n            assertDownloadSha1HeaderAgreement(expectedSha1, rangeSha1)\n          }\n          if (expectedSha1 !== null) {\n            assembledSha1 ??= new IncrementalSha1()\n            await assembledSha1.update(result.data)\n          }\n          controller.enqueue(result.data)\n        }\n\n        // Top up the window now that we freed a slot by emitting.\n        scheduleNext()\n\n        if (\n          nextToEmit >= ranges.length &&\n          buffer.size === 0 &&\n          inflight.size === 0 &&\n          firstError === null\n        ) {\n          if (expectedSha1 !== undefined && expectedSha1 !== null && assembledSha1 !== null) {\n            assertDownloadSha1(expectedSha1, await assembledSha1.digest())\n          }\n          controller.close()\n        }\n      } catch (err) {\n        controller.error(err)\n      }\n    },\n    cancel() {\n      // Abort propagation handles in-flight requests; just drop buffered\n      // data so it can be GC'd promptly.\n      buffer.clear()\n    },\n  })\n}\n\n/**\n * Fetches a single byte range with bounded retry on transient failures.\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param fileId - ID of the file being downloaded.\n * @param start - Inclusive byte offset where the range begins.\n * @param end - Inclusive byte offset where the range ends.\n * @param totalSize - Expected complete file size.\n * @param retryOptions - Retry settings controlling attempts and backoff.\n * @param signal - Optional abort signal that cancels the range and any pending retry.\n *\n * @returns The range's bytes, or throws after exhausting all retry attempts.\n */\nasync function fetchRangeWithRetry(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  fileId: FileId,\n  start: number,\n  end: number,\n  totalSize: number,\n  retryOptions: RetryOptions,\n  signal: AbortSignal | undefined,\n): Promise<RangeDownloadResult> {\n  let lastError: unknown\n  for (let attempt = 0; attempt <= retryOptions.maxRetries; attempt++) {\n    if (attempt > 0) {\n      const retryAfter =\n        lastError instanceof B2Error && lastError.retryAfter !== undefined\n          ? lastError.retryAfter\n          : undefined\n      const delay = computeBackoff(attempt - 1, retryOptions, retryAfter)\n      await sleep(delay, signal)\n    }\n    try {\n      signal?.throwIfAborted()\n      const resp = await raw.downloadFileById(\n        accountInfo.getDownloadUrl(),\n        accountInfo.getAuthToken(),\n        fileId,\n        {\n          range: byteRangeHeader(start, end),\n          ...(signal !== undefined ? { signal } : {}),\n        },\n      )\n      if (resp.status < 200 || resp.status >= 300) {\n        throw await classifyDownloadResponseError(resp)\n      }\n      if (!resp.body) throw new Error('Download chunk has no body')\n      const data = await collectStream(resp.body)\n      validateRangeResponse(resp, start, end, totalSize, data.byteLength)\n      return {\n        data,\n        contentSha1: normalizeSha1(resp.headers.get('X-Bz-Content-Sha1')),\n      }\n    } catch (err) {\n      lastError = err\n      // Honour AbortSignal cancellation: don't retry past an abort.\n      if (signal?.aborted) throw err\n      if (err instanceof DOMException && err.name === 'AbortError') throw err\n      if (!isRetryableRangeError(err) || attempt === retryOptions.maxRetries) {\n        throw err\n      }\n    }\n  }\n  throw lastError instanceof Error ? lastError : new Error('Range download failed after retries')\n}\n\nclass RangeValidationError extends Error {\n  readonly retryable = false\n\n  constructor(message: string) {\n    super(message)\n    this.name = 'RangeValidationError'\n  }\n}\n\nfunction validateRangeResponse(\n  response: { headers: Headers; status: number },\n  start: number,\n  end: number,\n  totalSize: number,\n  byteLength: number,\n): void {\n  const expectedLength = end - start + 1\n  if (response.status !== 206) {\n    throw new RangeValidationError(\n      `Expected HTTP 206 Partial Content for range ${start}-${end}, got ${response.status}`,\n    )\n  }\n\n  const contentRange = response.headers.get('Content-Range')\n  if (contentRange === null) {\n    throw new RangeValidationError(`Missing Content-Range for range ${start}-${end}`)\n  }\n\n  const match = contentRange.match(/^bytes (\\d+)-(\\d+)\\/(\\d+|\\*)$/)\n  if (match === null) {\n    throw new RangeValidationError(\n      `Invalid Content-Range for range ${start}-${end}: ${contentRange}`,\n    )\n  }\n\n  const actualStart = Number.parseInt(match[1] ?? '', 10)\n  const actualEnd = Number.parseInt(match[2] ?? '', 10)\n  const actualTotal = match[3] ?? ''\n  if (actualStart !== start || actualEnd !== end) {\n    throw new RangeValidationError(\n      `Content-Range ${contentRange} does not match requested range ${start}-${end}`,\n    )\n  }\n\n  if (actualTotal === '*') {\n    throw new RangeValidationError(`Content-Range ${contentRange} does not include total size`)\n  }\n\n  const parsedTotal = Number.parseInt(actualTotal, 10)\n  if (parsedTotal !== totalSize) {\n    throw new RangeValidationError(\n      `Content-Range ${contentRange} does not match expected total size ${totalSize}`,\n    )\n  }\n\n  if (byteLength !== expectedLength) {\n    throw new RangeValidationError(\n      `Expected ${expectedLength} bytes for range ${start}-${end}, got ${byteLength}`,\n    )\n  }\n}\n\nasync function classifyDownloadResponseError(response: {\n  headers: Headers\n  status: number\n  body: ReadableStream<Uint8Array> | null\n}): Promise<B2Error> {\n  let errorBody: B2ErrorResponse = {\n    status: response.status,\n    code: 'internal_error',\n    message: `HTTP ${response.status}`,\n  }\n\n  if (response.body !== null) {\n    const bytes = await collectStream(response.body)\n    try {\n      const parsed = JSON.parse(utf8Decoder.decode(bytes)) as Partial<B2ErrorResponse>\n      errorBody = {\n        status: response.status,\n        code: parsed.code ?? 'internal_error',\n        message: parsed.message ?? `HTTP ${response.status}`,\n      }\n    } catch {\n      // Keep the synthetic errorBody above when the response body is not JSON.\n    }\n  }\n\n  const retryAfterHeader = response.headers.get('Retry-After')\n  const retryAfter = retryAfterHeader !== null ? Number.parseInt(retryAfterHeader, 10) : undefined\n  const requestId = response.headers.get('X-Bz-Request-Id') ?? undefined\n\n  return classifyError(errorBody, {\n    ...(retryAfter !== undefined ? { retryAfter } : {}),\n    ...(requestId !== undefined ? { requestId } : {}),\n  })\n}\n\nfunction isRetryableRangeError(err: unknown): boolean {\n  if (err instanceof B2Error || err instanceof NetworkError) return err.retryable\n  if (hasRetryableFlag(err)) return err.retryable\n  // Bare FetchTransport surfaces network failures as TypeError. Validation\n  // failures use RangeValidationError above, so they never land here.\n  return err instanceof TypeError\n}\n\nfunction hasRetryableFlag(err: unknown): err is { retryable: boolean } {\n  return (\n    typeof err === 'object' &&\n    err !== null &&\n    'retryable' in err &&\n    typeof (err as { retryable?: unknown }).retryable === 'boolean'\n  )\n}\n"],"mappings":"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"}
+{"version":3,"file":"parallel.cjs","names":[],"sources":["../../src/download/parallel.ts"],"sourcesContent":["import type { AccountInfo } from '../auth/account-info.ts'\nimport { B2Error, classifyError, NetworkError } from '../errors/index.ts'\nimport { computeBackoff, DEFAULT_RETRY_OPTIONS, type RetryOptions, sleep } from '../http/retry.ts'\nimport type { RawClient, SseCDownloadKey } from '../raw/index.ts'\nimport { collectStream } from '../streams/collect.ts'\nimport { IncrementalSha1 } from '../streams/hash.ts'\nimport { redactSseCKeyMaterial } from '../types/encryption.ts'\nimport type { B2ErrorResponse } from '../types/errors.ts'\nimport type { FileId } from '../types/ids.ts'\nimport { DEFAULT_DOWNLOAD_RANGE_SIZE, DEFAULT_TRANSFER_CONCURRENCY } from '../util/defaults.ts'\nimport { normalizeSha1 } from '../util/normalize.ts'\nimport { byteRangeHeader, planRanges } from '../util/plan-ranges.ts'\nimport { normalizeVerifiableSha1 } from '../util/sha1.ts'\nimport { utf8Decoder } from '../util/text-codec.ts'\nimport { assertDownloadSha1, assertDownloadSha1HeaderAgreement } from './checksum.ts'\n\n/** Options for downloading a file using concurrent byte-range requests. */\nexport interface ParallelDownloadOptions {\n  /** ID of the file to download. */\n  readonly fileId: FileId\n  /** Total file size in bytes (must be known in advance). */\n  readonly totalSize: number\n  /** Size of each ranged chunk in bytes. Defaults to 10 MB. */\n  readonly rangeSize?: number\n  /** Maximum number of chunks fetched in parallel. Defaults to 4. */\n  readonly concurrency?: number\n  /**\n   * SSE-C decryption parameters, required if the file was uploaded with SSE-C.\n   * Internal diagnostics redact the copied options object, but the key is still\n   * sent in plaintext SSE-C HTTP headers. Custom transports should not log\n   * request headers that may contain customer-provided keys.\n   */\n  readonly serverSideEncryption?: SseCDownloadKey\n  /**\n   * Extra retry attempts per range on transient failures. Defaults to 0 because\n   * `B2Client` already applies `RetryTransport`; set this only when supplying a\n   * raw client that does not already retry transport failures.\n   */\n  readonly maxRetries?: number\n  /** Signal to abort the download. */\n  readonly signal?: AbortSignal\n}\n\ninterface RangeDownloadResult {\n  readonly data: Uint8Array\n  readonly contentSha1: string | null\n}\n\ninterface FetchRangeWithRetryParams {\n  readonly raw: RawClient\n  readonly accountInfo: AccountInfo\n  readonly fileId: FileId\n  readonly start: number\n  readonly end: number\n  readonly totalSize: number\n  readonly serverSideEncryption: SseCDownloadKey | undefined\n  readonly retryOptions: RetryOptions\n  readonly signal: AbortSignal | undefined\n}\n\n/**\n * Creates a readable stream that downloads a file using parallel byte-range requests.\n *\n * The file is split into fixed-size ranges fetched in a **sliding\n * window** keyed off the consumer's read pace. The window size is\n * `concurrency * 2`: up to `concurrency` ranges are in flight at once,\n * plus up to `concurrency` completed-but-not-yet-emitted ranges buffered\n * ahead of the read head. New fetches kick off only when the consumer\n * reads a chunk, so a slow downstream pipe (e.g. a saturated network\n * sink or a `pipeTo` consumer that drains slowly) backpressures into\n * the SDK and bounds peak memory to `(concurrency * 2) * rangeSize`.\n *\n * The previous eager implementation scheduled every range into\n * `Promise.all` up front; a slow head-of-line range could hold the\n * entire file in memory while later ranges finished and waited.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param options - Parallel download parameters (file ID, size, concurrency).\n *\n * @returns A `ReadableStream` that yields file bytes in order.\n */\nexport function createParallelDownloadStream(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  options: ParallelDownloadOptions,\n): ReadableStream<Uint8Array> {\n  const rangeSize = options.rangeSize ?? DEFAULT_DOWNLOAD_RANGE_SIZE\n  const concurrency = options.concurrency ?? DEFAULT_TRANSFER_CONCURRENCY\n  const totalSize = options.totalSize\n  const serverSideEncryption =\n    options.serverSideEncryption !== undefined\n      ? redactSseCKeyMaterial(options.serverSideEncryption, { label: 'SseCDownloadKey' })\n      : undefined\n  // The high-level B2Client already wraps the raw transport in RetryTransport.\n  // Keep the parallel-download outer retry disabled by default so each range\n  // has one retry budget unless callers explicitly opt into an extra raw-client\n  // retry layer.\n  const retryOptions = {\n    ...DEFAULT_RETRY_OPTIONS,\n    maxRetries: options.maxRetries ?? 0,\n  }\n  const internalAbort = new AbortController()\n  const abort = internalAbort.signal\n  let removeCallerAbortListener: (() => void) | undefined\n  if (options.signal !== undefined) {\n    if (options.signal.aborted) {\n      internalAbort.abort(options.signal.reason)\n    } else {\n      const callerSignal = options.signal\n      const abortFromCaller = () => internalAbort.abort(callerSignal.reason)\n      callerSignal.addEventListener('abort', abortFromCaller, { once: true })\n      removeCallerAbortListener = () => callerSignal.removeEventListener('abort', abortFromCaller)\n    }\n  }\n\n  const ranges = planRanges(totalSize, rangeSize)\n\n  // `inflight` holds currently-fetching range promises; `buffer` holds\n  // completed ranges waiting for their slot in the emit order. Total\n  // scheduled-but-not-emitted = inflight.size + buffer.size is capped\n  // at `windowSize`, so peak memory is bounded regardless of any\n  // single range's latency.\n  const windowSize = concurrency * 2\n  const inflight = new Map<number, Promise<void>>()\n  const buffer = new Map<number, RangeDownloadResult>()\n  let assembledSha1: IncrementalSha1 | null = null\n  let nextToSchedule = 0\n  let nextToEmit = 0\n  let expectedSha1: string | null | undefined\n  let firstError: unknown = null\n\n  function abortInflight(reason?: unknown): void {\n    if (!abort.aborted) internalAbort.abort(reason)\n  }\n\n  function cleanupCallerAbortListener(): void {\n    removeCallerAbortListener?.()\n    removeCallerAbortListener = undefined\n  }\n\n  function scheduleNext(): void {\n    while (\n      firstError === null &&\n      // Honour abort here so a completed range that triggers a top-up\n      // doesn't queue one final fetch after the caller aborted. Without\n      // this gate, one extra range request fires post-abort before the\n      // `pull()` loop notices.\n      abort?.aborted !== true &&\n      nextToSchedule < ranges.length &&\n      inflight.size + buffer.size < windowSize\n    ) {\n      const range = ranges[nextToSchedule]\n      if (range === undefined) break\n      const idx = nextToSchedule\n      nextToSchedule++\n      const task = (async () => {\n        try {\n          const result = await fetchRangeWithRetry({\n            raw,\n            accountInfo,\n            fileId: options.fileId,\n            start: range.start,\n            end: range.end,\n            totalSize,\n            serverSideEncryption,\n            retryOptions,\n            signal: abort,\n          })\n          buffer.set(idx, result)\n        } catch (err) {\n          if (firstError === null) {\n            firstError = err\n            abortInflight(err)\n          }\n        } finally {\n          inflight.delete(idx)\n        }\n      })()\n      inflight.set(idx, task)\n    }\n  }\n\n  return new ReadableStream<Uint8Array>({\n    start(controller) {\n      // Pre-warm: kick off the initial window so the first `pull` has\n      // something to await. An already-aborted signal surfaces as a\n      // stream error rather than a synchronous throw, matching the\n      // contract callers had with the previous eager implementation.\n      try {\n        abort?.throwIfAborted()\n        scheduleNext()\n      } catch (err) {\n        cleanupCallerAbortListener()\n        controller.error(err)\n      }\n    },\n    async pull(controller) {\n      try {\n        // Wait until the next in-order chunk is available.\n        while (!buffer.has(nextToEmit)) {\n          abort?.throwIfAborted()\n          if (firstError !== null) throw firstError\n          // Zero-byte downloads have no planned ranges and close here. For\n          // non-empty downloads, this guard prevents a future refactor from\n          // stalling the stream if it leaves both maps empty mid-stream.\n          if (inflight.size === 0) {\n            cleanupCallerAbortListener()\n            controller.close()\n            return\n          }\n          await Promise.race(inflight.values())\n        }\n\n        const result = buffer.get(nextToEmit)\n        if (result !== undefined) {\n          buffer.delete(nextToEmit)\n          nextToEmit++\n          const rangeSha1 = normalizeVerifiableSha1(result.contentSha1)\n          if (expectedSha1 === undefined) {\n            expectedSha1 = rangeSha1\n          } else {\n            // B2 range responses should agree on the same whole-file SHA-1;\n            // any value or presence change makes verification untrustworthy.\n            assertDownloadSha1HeaderAgreement(expectedSha1, rangeSha1)\n          }\n          if (expectedSha1 !== null) {\n            assembledSha1 ??= new IncrementalSha1()\n            await assembledSha1.update(result.data)\n          }\n          controller.enqueue(result.data)\n        }\n\n        // Top up the window now that we freed a slot by emitting.\n        scheduleNext()\n\n        if (\n          nextToEmit >= ranges.length &&\n          buffer.size === 0 &&\n          inflight.size === 0 &&\n          firstError === null\n        ) {\n          if (expectedSha1 !== undefined && expectedSha1 !== null && assembledSha1 !== null) {\n            assertDownloadSha1(expectedSha1, await assembledSha1.digest())\n          }\n          cleanupCallerAbortListener()\n          controller.close()\n        }\n      } catch (err) {\n        abortInflight(err)\n        cleanupCallerAbortListener()\n        controller.error(err)\n      }\n    },\n    cancel(reason) {\n      abortInflight(reason)\n      cleanupCallerAbortListener()\n      // Abort propagation handles in-flight requests; just drop buffered\n      // data so it can be GC'd promptly.\n      buffer.clear()\n    },\n  })\n}\n\n/**\n * Fetches a single byte range with bounded retry on transient failures.\n * @param params - Range request parameters, retry settings, and cancellation.\n *\n * @returns The range's bytes, or throws after exhausting all retry attempts.\n */\nasync function fetchRangeWithRetry(\n  params: FetchRangeWithRetryParams,\n): Promise<RangeDownloadResult> {\n  const {\n    raw,\n    accountInfo,\n    fileId,\n    start,\n    end,\n    totalSize,\n    serverSideEncryption,\n    retryOptions,\n    signal,\n  } = params\n  let lastError: unknown\n  for (let attempt = 0; attempt <= retryOptions.maxRetries; attempt++) {\n    if (attempt > 0) {\n      const retryAfter =\n        lastError instanceof B2Error && lastError.retryAfter !== undefined\n          ? lastError.retryAfter\n          : undefined\n      const delay = computeBackoff(attempt - 1, retryOptions, retryAfter)\n      await sleep(delay, signal)\n    }\n    try {\n      signal?.throwIfAborted()\n      const resp = await raw.downloadFileById(\n        accountInfo.getDownloadUrl(),\n        accountInfo.getAuthToken(),\n        fileId,\n        {\n          range: byteRangeHeader(start, end),\n          ...(serverSideEncryption !== undefined ? { serverSideEncryption } : {}),\n          ...(signal !== undefined ? { signal } : {}),\n        },\n      )\n      if (resp.status < 200 || resp.status >= 300) {\n        throw await classifyDownloadResponseError(resp)\n      }\n      if (!resp.body) throw new Error('Download chunk has no body')\n      const data = await collectStream(resp.body)\n      validateRangeResponse(resp, start, end, totalSize, data.byteLength)\n      return {\n        data,\n        contentSha1: normalizeSha1(resp.headers.get('X-Bz-Content-Sha1')),\n      }\n    } catch (err) {\n      lastError = err\n      // Honour AbortSignal cancellation: don't retry past an abort.\n      if (signal?.aborted) throw err\n      if (err instanceof DOMException && err.name === 'AbortError') throw err\n      if (!isRetryableRangeError(err) || attempt === retryOptions.maxRetries) {\n        throw err\n      }\n    }\n  }\n  throw lastError instanceof Error ? lastError : new Error('Range download failed after retries')\n}\n\nclass RangeValidationError extends Error {\n  readonly retryable = false\n\n  constructor(message: string) {\n    super(message)\n    this.name = 'RangeValidationError'\n  }\n}\n\nfunction validateRangeResponse(\n  response: { headers: Headers; status: number },\n  start: number,\n  end: number,\n  totalSize: number,\n  byteLength: number,\n): void {\n  const expectedLength = end - start + 1\n  if (response.status !== 206) {\n    throw new RangeValidationError(\n      `Expected HTTP 206 Partial Content for range ${start}-${end}, got ${response.status}`,\n    )\n  }\n\n  const contentRange = response.headers.get('Content-Range')\n  if (contentRange === null) {\n    throw new RangeValidationError(`Missing Content-Range for range ${start}-${end}`)\n  }\n\n  const match = contentRange.match(/^bytes (\\d+)-(\\d+)\\/(\\d+|\\*)$/)\n  if (match === null) {\n    throw new RangeValidationError(\n      `Invalid Content-Range for range ${start}-${end}: ${contentRange}`,\n    )\n  }\n\n  const actualStart = Number.parseInt(match[1] ?? '', 10)\n  const actualEnd = Number.parseInt(match[2] ?? '', 10)\n  const actualTotal = match[3] ?? ''\n  if (actualStart !== start || actualEnd !== end) {\n    throw new RangeValidationError(\n      `Content-Range ${contentRange} does not match requested range ${start}-${end}`,\n    )\n  }\n\n  if (actualTotal === '*') {\n    throw new RangeValidationError(`Content-Range ${contentRange} does not include total size`)\n  }\n\n  const parsedTotal = Number.parseInt(actualTotal, 10)\n  if (parsedTotal !== totalSize) {\n    throw new RangeValidationError(\n      `Content-Range ${contentRange} does not match expected total size ${totalSize}`,\n    )\n  }\n\n  if (byteLength !== expectedLength) {\n    throw new RangeValidationError(\n      `Expected ${expectedLength} bytes for range ${start}-${end}, got ${byteLength}`,\n    )\n  }\n}\n\nasync function classifyDownloadResponseError(response: {\n  headers: Headers\n  status: number\n  body: ReadableStream<Uint8Array> | null\n}): Promise<B2Error> {\n  let errorBody: B2ErrorResponse = {\n    status: response.status,\n    code: 'internal_error',\n    message: `HTTP ${response.status}`,\n  }\n\n  if (response.body !== null) {\n    const bytes = await collectStream(response.body)\n    try {\n      const parsed = JSON.parse(utf8Decoder.decode(bytes)) as Partial<B2ErrorResponse>\n      errorBody = {\n        status: response.status,\n        code: parsed.code ?? 'internal_error',\n        message: parsed.message ?? `HTTP ${response.status}`,\n      }\n    } catch {\n      // Keep the synthetic errorBody above when the response body is not JSON.\n    }\n  }\n\n  const retryAfterHeader = response.headers.get('Retry-After')\n  const retryAfter = retryAfterHeader !== null ? Number.parseInt(retryAfterHeader, 10) : undefined\n  const requestId = response.headers.get('X-Bz-Request-Id') ?? undefined\n\n  return classifyError(errorBody, {\n    ...(retryAfter !== undefined ? { retryAfter } : {}),\n    ...(requestId !== undefined ? { requestId } : {}),\n  })\n}\n\nfunction isRetryableRangeError(err: unknown): boolean {\n  if (err instanceof B2Error || err instanceof NetworkError) return err.retryable\n  if (hasRetryableFlag(err)) return err.retryable\n  // Bare FetchTransport surfaces network failures as TypeError. Validation\n  // failures use RangeValidationError above, so they never land here.\n  return err instanceof TypeError\n}\n\nfunction hasRetryableFlag(err: unknown): err is { retryable: boolean } {\n  return (\n    typeof err === 'object' &&\n    err !== null &&\n    'retryable' in err &&\n    typeof (err as { retryable?: unknown }).retryable === 'boolean'\n  )\n}\n"],"mappings":"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"}

package/dist/download/parallel.d.cts

@@ -1,5 +1,5 @@
 import { AccountInfo } from '../auth/account-info.js';
-import { RawClient } from '../raw/index.js';
+import { RawClient, SseCDownloadKey } from '../raw/index.js';
 import { FileId } from '../types/ids.js';
 /** Options for downloading a file using concurrent byte-range requests. */
 export interface ParallelDownloadOptions {
@@ -11,6 +11,13 @@ export interface ParallelDownloadOptions {
     readonly rangeSize?: number;
     /** Maximum number of chunks fetched in parallel. Defaults to 4. */
     readonly concurrency?: number;
+    /**
+     * SSE-C decryption parameters, required if the file was uploaded with SSE-C.
+     * Internal diagnostics redact the copied options object, but the key is still
+     * sent in plaintext SSE-C HTTP headers. Custom transports should not log
+     * request headers that may contain customer-provided keys.
+     */
+    readonly serverSideEncryption?: SseCDownloadKey;
     /**
      * Extra retry attempts per range on transient failures. Defaults to 0 because
      * `B2Client` already applies `RetryTransport`; set this only when supplying a

package/dist/download/parallel.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"parallel.d.ts","sourceRoot":"","sources":["../../src/download/parallel.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAG1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAIhD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAQ7C,2EAA2E;AAC3E,MAAM,WAAW,uBAAuB;IACtC,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAOD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,SAAS,EACd,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,uBAAuB,GAC/B,cAAc,CAAC,UAAU,CAAC,CA4I5B"}
+{"version":3,"file":"parallel.d.ts","sourceRoot":"","sources":["../../src/download/parallel.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAG1D,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAKjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAQ7C,2EAA2E;AAC3E,MAAM,WAAW,uBAAuB;IACtC,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,eAAe,CAAA;IAC/C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAmBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,SAAS,EACd,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,uBAAuB,GAC/B,cAAc,CAAC,UAAU,CAAC,CAgL5B"}

package/dist/download/parallel.d.ts

@@ -1,5 +1,5 @@
 import { AccountInfo } from '../auth/account-info.js';
-import { RawClient } from '../raw/index.js';
+import { RawClient, SseCDownloadKey } from '../raw/index.js';
 import { FileId } from '../types/ids.js';
 /** Options for downloading a file using concurrent byte-range requests. */
 export interface ParallelDownloadOptions {
@@ -11,6 +11,13 @@ export interface ParallelDownloadOptions {
     readonly rangeSize?: number;
     /** Maximum number of chunks fetched in parallel. Defaults to 4. */
     readonly concurrency?: number;
+    /**
+     * SSE-C decryption parameters, required if the file was uploaded with SSE-C.
+     * Internal diagnostics redact the copied options object, but the key is still
+     * sent in plaintext SSE-C HTTP headers. Custom transports should not log
+     * request headers that may contain customer-provided keys.
+     */
+    readonly serverSideEncryption?: SseCDownloadKey;
     /**
      * Extra retry attempts per range on transient failures. Defaults to 0 because
      * `B2Client` already applies `RetryTransport`; set this only when supplying a

package/dist/download/parallel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parallel.d.ts","sourceRoot":"","sources":["../../src/download/parallel.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAG1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAIhD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAQ7C,2EAA2E;AAC3E,MAAM,WAAW,uBAAuB;IACtC,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAOD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,SAAS,EACd,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,uBAAuB,GAC/B,cAAc,CAAC,UAAU,CAAC,CA4I5B"}
+{"version":3,"file":"parallel.d.ts","sourceRoot":"","sources":["../../src/download/parallel.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAG1D,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAKjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAQ7C,2EAA2E;AAC3E,MAAM,WAAW,uBAAuB;IACtC,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,eAAe,CAAA;IAC/C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAmBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,SAAS,EACd,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,uBAAuB,GAC/B,cAAc,CAAC,UAAU,CAAC,CAgL5B"}

package/dist/download/parallel.js

@@ -1,6 +1,8 @@
 import { B2Error, NetworkError, classifyError } from "../errors/index.js";
+import "../util/defaults.js";
 import { byteRangeHeader, planRanges } from "../util/plan-ranges.js";
 import { utf8Decoder } from "../util/text-codec.js";
+import { redactSseCKeyMaterial } from "../types/encryption.js";
 import { normalizeSha1 } from "../util/normalize.js";
 import { IncrementalSha1 } from "../streams/hash.js";
 import { normalizeVerifiableSha1 } from "../util/sha1.js";
@@ -31,14 +33,26 @@ import { collectStream } from "../streams/collect.js";
 * @returns A `ReadableStream` that yields file bytes in order.
 */
 function createParallelDownloadStream(raw, accountInfo, options) {
-	const rangeSize = options.rangeSize ?? 10 * 1024 * 1024;
+	const rangeSize = options.rangeSize ?? 10485760;
 	const concurrency = options.concurrency ?? 4;
 	const totalSize = options.totalSize;
+	const serverSideEncryption = options.serverSideEncryption !== void 0 ? redactSseCKeyMaterial(options.serverSideEncryption, { label: "SseCDownloadKey" }) : void 0;
 	const retryOptions = {
 		...DEFAULT_RETRY_OPTIONS,
 		maxRetries: options.maxRetries ?? 0
 	};
-	const abort = options.signal;
+	const internalAbort = new AbortController();
+	const abort = internalAbort.signal;
+	let removeCallerAbortListener;
+	if (options.signal !== void 0) {
+		if (options.signal.aborted) internalAbort.abort(options.signal.reason);
+		else {
+			const callerSignal = options.signal;
+			const abortFromCaller = () => internalAbort.abort(callerSignal.reason);
+			callerSignal.addEventListener("abort", abortFromCaller, { once: true });
+			removeCallerAbortListener = () => callerSignal.removeEventListener("abort", abortFromCaller);
+		}
+	}
 	const ranges = planRanges(totalSize, rangeSize);
 	const windowSize = concurrency * 2;
 	const inflight = /* @__PURE__ */ new Map();
@@ -48,6 +62,13 @@ function createParallelDownloadStream(raw, accountInfo, options) {
 	let nextToEmit = 0;
 	let expectedSha1;
 	let firstError = null;
+	function abortInflight(reason) {
+		if (!abort.aborted) internalAbort.abort(reason);
+	}
+	function cleanupCallerAbortListener() {
+		removeCallerAbortListener?.();
+		removeCallerAbortListener = void 0;
+	}
 	function scheduleNext() {
 		while (firstError === null && abort?.aborted !== true && nextToSchedule < ranges.length && inflight.size + buffer.size < windowSize) {
 			const range = ranges[nextToSchedule];
@@ -56,10 +77,23 @@ function createParallelDownloadStream(raw, accountInfo, options) {
 			nextToSchedule++;
 			const task = (async () => {
 				try {
-					const result = await fetchRangeWithRetry(raw, accountInfo, options.fileId, range.start, range.end, totalSize, retryOptions, abort);
+					const result = await fetchRangeWithRetry({
+						raw,
+						accountInfo,
+						fileId: options.fileId,
+						start: range.start,
+						end: range.end,
+						totalSize,
+						serverSideEncryption,
+						retryOptions,
+						signal: abort
+					});
 					buffer.set(idx, result);
 				} catch (err) {
-					if (firstError === null) firstError = err;
+					if (firstError === null) {
+						firstError = err;
+						abortInflight(err);
+					}
 				} finally {
 					inflight.delete(idx);
 				}
@@ -73,6 +107,7 @@ function createParallelDownloadStream(raw, accountInfo, options) {
 				abort?.throwIfAborted();
 				scheduleNext();
 			} catch (err) {
+				cleanupCallerAbortListener();
 				controller.error(err);
 			}
 		},
@@ -82,6 +117,7 @@ function createParallelDownloadStream(raw, accountInfo, options) {
 					abort?.throwIfAborted();
 					if (firstError !== null) throw firstError;
 					if (inflight.size === 0) {
+						cleanupCallerAbortListener();
 						controller.close();
 						return;
 					}
@@ -103,41 +139,42 @@ function createParallelDownloadStream(raw, accountInfo, options) {
 				scheduleNext();
 				if (nextToEmit >= ranges.length && buffer.size === 0 && inflight.size === 0 && firstError === null) {
 					if (expectedSha1 !== void 0 && expectedSha1 !== null && assembledSha1 !== null) assertDownloadSha1(expectedSha1, await assembledSha1.digest());
+					cleanupCallerAbortListener();
 					controller.close();
 				}
 			} catch (err) {
+				abortInflight(err);
+				cleanupCallerAbortListener();
 				controller.error(err);
 			}
 		},
-		cancel() {
+		cancel(reason) {
+			abortInflight(reason);
+			cleanupCallerAbortListener();
 			buffer.clear();
 		}
 	});
 }
 /**
 * Fetches a single byte range with bounded retry on transient failures.
-* @param raw - Low-level B2 API client.
-* @param accountInfo - Authorized account state.
-* @param fileId - ID of the file being downloaded.
-* @param start - Inclusive byte offset where the range begins.
-* @param end - Inclusive byte offset where the range ends.
-* @param totalSize - Expected complete file size.
-* @param retryOptions - Retry settings controlling attempts and backoff.
-* @param signal - Optional abort signal that cancels the range and any pending retry.
+* @param params - Range request parameters, retry settings, and cancellation.
 *
 * @returns The range's bytes, or throws after exhausting all retry attempts.
 */
-async function fetchRangeWithRetry(raw, accountInfo, fileId, start, end, totalSize, retryOptions, signal) {
+async function fetchRangeWithRetry(params) {
+	const { raw, accountInfo, fileId, start, end, totalSize, serverSideEncryption, retryOptions, signal } = params;
 	let lastError;
 	for (let attempt = 0; attempt <= retryOptions.maxRetries; attempt++) {
 		if (attempt > 0) {
 			const retryAfter = lastError instanceof B2Error && lastError.retryAfter !== void 0 ? lastError.retryAfter : void 0;
-			await sleep(computeBackoff(attempt - 1, retryOptions, retryAfter), signal);
+			const delay = computeBackoff(attempt - 1, retryOptions, retryAfter);
+			await sleep(delay, signal);
 		}
 		try {
 			signal?.throwIfAborted();
 			const resp = await raw.downloadFileById(accountInfo.getDownloadUrl(), accountInfo.getAuthToken(), fileId, {
 				range: byteRangeHeader(start, end),
+				...serverSideEncryption !== void 0 ? { serverSideEncryption } : {},
 				...signal !== void 0 ? { signal } : {}
 			});
 			if (resp.status < 200 || resp.status >= 300) throw await classifyDownloadResponseError(resp);

package/dist/download/parallel.js.map

@@ -1 +1 @@
-{"version":3,"file":"parallel.js","names":[],"sources":["../../src/download/parallel.ts"],"sourcesContent":["import type { AccountInfo } from '../auth/account-info.ts'\nimport { B2Error, classifyError, NetworkError } from '../errors/index.ts'\nimport { computeBackoff, DEFAULT_RETRY_OPTIONS, type RetryOptions, sleep } from '../http/retry.ts'\nimport type { RawClient } from '../raw/index.ts'\nimport { collectStream } from '../streams/collect.ts'\nimport { IncrementalSha1 } from '../streams/hash.ts'\nimport type { B2ErrorResponse } from '../types/errors.ts'\nimport type { FileId } from '../types/ids.ts'\nimport { DEFAULT_TRANSFER_CONCURRENCY } from '../util/defaults.ts'\nimport { normalizeSha1 } from '../util/normalize.ts'\nimport { byteRangeHeader, planRanges } from '../util/plan-ranges.ts'\nimport { normalizeVerifiableSha1 } from '../util/sha1.ts'\nimport { utf8Decoder } from '../util/text-codec.ts'\nimport { assertDownloadSha1, assertDownloadSha1HeaderAgreement } from './checksum.ts'\n\n/** Options for downloading a file using concurrent byte-range requests. */\nexport interface ParallelDownloadOptions {\n  /** ID of the file to download. */\n  readonly fileId: FileId\n  /** Total file size in bytes (must be known in advance). */\n  readonly totalSize: number\n  /** Size of each ranged chunk in bytes. Defaults to 10 MB. */\n  readonly rangeSize?: number\n  /** Maximum number of chunks fetched in parallel. Defaults to 4. */\n  readonly concurrency?: number\n  /**\n   * Extra retry attempts per range on transient failures. Defaults to 0 because\n   * `B2Client` already applies `RetryTransport`; set this only when supplying a\n   * raw client that does not already retry transport failures.\n   */\n  readonly maxRetries?: number\n  /** Signal to abort the download. */\n  readonly signal?: AbortSignal\n}\n\ninterface RangeDownloadResult {\n  readonly data: Uint8Array\n  readonly contentSha1: string | null\n}\n\n/**\n * Creates a readable stream that downloads a file using parallel byte-range requests.\n *\n * The file is split into fixed-size ranges fetched in a **sliding\n * window** keyed off the consumer's read pace. The window size is\n * `concurrency * 2`: up to `concurrency` ranges are in flight at once,\n * plus up to `concurrency` completed-but-not-yet-emitted ranges buffered\n * ahead of the read head. New fetches kick off only when the consumer\n * reads a chunk, so a slow downstream pipe (e.g. a saturated network\n * sink or a `pipeTo` consumer that drains slowly) backpressures into\n * the SDK and bounds peak memory to `(concurrency * 2) * rangeSize`.\n *\n * The previous eager implementation scheduled every range into\n * `Promise.all` up front; a slow head-of-line range could hold the\n * entire file in memory while later ranges finished and waited.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param options - Parallel download parameters (file ID, size, concurrency).\n *\n * @returns A `ReadableStream` that yields file bytes in order.\n */\nexport function createParallelDownloadStream(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  options: ParallelDownloadOptions,\n): ReadableStream<Uint8Array> {\n  const rangeSize = options.rangeSize ?? 10 * 1024 * 1024\n  const concurrency = options.concurrency ?? DEFAULT_TRANSFER_CONCURRENCY\n  const totalSize = options.totalSize\n  // The high-level B2Client already wraps the raw transport in RetryTransport.\n  // Keep the parallel-download outer retry disabled by default so each range\n  // has one retry budget unless callers explicitly opt into an extra raw-client\n  // retry layer.\n  const retryOptions = {\n    ...DEFAULT_RETRY_OPTIONS,\n    maxRetries: options.maxRetries ?? 0,\n  }\n  const abort = options.signal\n\n  const ranges = planRanges(totalSize, rangeSize)\n\n  // `inflight` holds currently-fetching range promises; `buffer` holds\n  // completed ranges waiting for their slot in the emit order. Total\n  // scheduled-but-not-emitted = inflight.size + buffer.size is capped\n  // at `windowSize`, so peak memory is bounded regardless of any\n  // single range's latency.\n  const windowSize = concurrency * 2\n  const inflight = new Map<number, Promise<void>>()\n  const buffer = new Map<number, RangeDownloadResult>()\n  let assembledSha1: IncrementalSha1 | null = null\n  let nextToSchedule = 0\n  let nextToEmit = 0\n  let expectedSha1: string | null | undefined\n  let firstError: unknown = null\n\n  function scheduleNext(): void {\n    while (\n      firstError === null &&\n      // Honour abort here so a completed range that triggers a top-up\n      // doesn't queue one final fetch after the caller aborted. Without\n      // this gate, one extra range request fires post-abort before the\n      // `pull()` loop notices.\n      abort?.aborted !== true &&\n      nextToSchedule < ranges.length &&\n      inflight.size + buffer.size < windowSize\n    ) {\n      const range = ranges[nextToSchedule]\n      if (range === undefined) break\n      const idx = nextToSchedule\n      nextToSchedule++\n      const task = (async () => {\n        try {\n          const result = await fetchRangeWithRetry(\n            raw,\n            accountInfo,\n            options.fileId,\n            range.start,\n            range.end,\n            totalSize,\n            retryOptions,\n            abort,\n          )\n          buffer.set(idx, result)\n        } catch (err) {\n          if (firstError === null) firstError = err\n        } finally {\n          inflight.delete(idx)\n        }\n      })()\n      inflight.set(idx, task)\n    }\n  }\n\n  return new ReadableStream<Uint8Array>({\n    start(controller) {\n      // Pre-warm: kick off the initial window so the first `pull` has\n      // something to await. An already-aborted signal surfaces as a\n      // stream error rather than a synchronous throw, matching the\n      // contract callers had with the previous eager implementation.\n      try {\n        abort?.throwIfAborted()\n        scheduleNext()\n      } catch (err) {\n        controller.error(err)\n      }\n    },\n    async pull(controller) {\n      try {\n        // Wait until the next in-order chunk is available.\n        while (!buffer.has(nextToEmit)) {\n          abort?.throwIfAborted()\n          if (firstError !== null) throw firstError\n          // Zero-byte downloads have no planned ranges and close here. For\n          // non-empty downloads, this guard prevents a future refactor from\n          // stalling the stream if it leaves both maps empty mid-stream.\n          if (inflight.size === 0) {\n            controller.close()\n            return\n          }\n          await Promise.race(inflight.values())\n        }\n\n        const result = buffer.get(nextToEmit)\n        if (result !== undefined) {\n          buffer.delete(nextToEmit)\n          nextToEmit++\n          const rangeSha1 = normalizeVerifiableSha1(result.contentSha1)\n          if (expectedSha1 === undefined) {\n            expectedSha1 = rangeSha1\n          } else {\n            // B2 range responses should agree on the same whole-file SHA-1;\n            // any value or presence change makes verification untrustworthy.\n            assertDownloadSha1HeaderAgreement(expectedSha1, rangeSha1)\n          }\n          if (expectedSha1 !== null) {\n            assembledSha1 ??= new IncrementalSha1()\n            await assembledSha1.update(result.data)\n          }\n          controller.enqueue(result.data)\n        }\n\n        // Top up the window now that we freed a slot by emitting.\n        scheduleNext()\n\n        if (\n          nextToEmit >= ranges.length &&\n          buffer.size === 0 &&\n          inflight.size === 0 &&\n          firstError === null\n        ) {\n          if (expectedSha1 !== undefined && expectedSha1 !== null && assembledSha1 !== null) {\n            assertDownloadSha1(expectedSha1, await assembledSha1.digest())\n          }\n          controller.close()\n        }\n      } catch (err) {\n        controller.error(err)\n      }\n    },\n    cancel() {\n      // Abort propagation handles in-flight requests; just drop buffered\n      // data so it can be GC'd promptly.\n      buffer.clear()\n    },\n  })\n}\n\n/**\n * Fetches a single byte range with bounded retry on transient failures.\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param fileId - ID of the file being downloaded.\n * @param start - Inclusive byte offset where the range begins.\n * @param end - Inclusive byte offset where the range ends.\n * @param totalSize - Expected complete file size.\n * @param retryOptions - Retry settings controlling attempts and backoff.\n * @param signal - Optional abort signal that cancels the range and any pending retry.\n *\n * @returns The range's bytes, or throws after exhausting all retry attempts.\n */\nasync function fetchRangeWithRetry(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  fileId: FileId,\n  start: number,\n  end: number,\n  totalSize: number,\n  retryOptions: RetryOptions,\n  signal: AbortSignal | undefined,\n): Promise<RangeDownloadResult> {\n  let lastError: unknown\n  for (let attempt = 0; attempt <= retryOptions.maxRetries; attempt++) {\n    if (attempt > 0) {\n      const retryAfter =\n        lastError instanceof B2Error && lastError.retryAfter !== undefined\n          ? lastError.retryAfter\n          : undefined\n      const delay = computeBackoff(attempt - 1, retryOptions, retryAfter)\n      await sleep(delay, signal)\n    }\n    try {\n      signal?.throwIfAborted()\n      const resp = await raw.downloadFileById(\n        accountInfo.getDownloadUrl(),\n        accountInfo.getAuthToken(),\n        fileId,\n        {\n          range: byteRangeHeader(start, end),\n          ...(signal !== undefined ? { signal } : {}),\n        },\n      )\n      if (resp.status < 200 || resp.status >= 300) {\n        throw await classifyDownloadResponseError(resp)\n      }\n      if (!resp.body) throw new Error('Download chunk has no body')\n      const data = await collectStream(resp.body)\n      validateRangeResponse(resp, start, end, totalSize, data.byteLength)\n      return {\n        data,\n        contentSha1: normalizeSha1(resp.headers.get('X-Bz-Content-Sha1')),\n      }\n    } catch (err) {\n      lastError = err\n      // Honour AbortSignal cancellation: don't retry past an abort.\n      if (signal?.aborted) throw err\n      if (err instanceof DOMException && err.name === 'AbortError') throw err\n      if (!isRetryableRangeError(err) || attempt === retryOptions.maxRetries) {\n        throw err\n      }\n    }\n  }\n  throw lastError instanceof Error ? lastError : new Error('Range download failed after retries')\n}\n\nclass RangeValidationError extends Error {\n  readonly retryable = false\n\n  constructor(message: string) {\n    super(message)\n    this.name = 'RangeValidationError'\n  }\n}\n\nfunction validateRangeResponse(\n  response: { headers: Headers; status: number },\n  start: number,\n  end: number,\n  totalSize: number,\n  byteLength: number,\n): void {\n  const expectedLength = end - start + 1\n  if (response.status !== 206) {\n    throw new RangeValidationError(\n      `Expected HTTP 206 Partial Content for range ${start}-${end}, got ${response.status}`,\n    )\n  }\n\n  const contentRange = response.headers.get('Content-Range')\n  if (contentRange === null) {\n    throw new RangeValidationError(`Missing Content-Range for range ${start}-${end}`)\n  }\n\n  const match = contentRange.match(/^bytes (\\d+)-(\\d+)\\/(\\d+|\\*)$/)\n  if (match === null) {\n    throw new RangeValidationError(\n      `Invalid Content-Range for range ${start}-${end}: ${contentRange}`,\n    )\n  }\n\n  const actualStart = Number.parseInt(match[1] ?? '', 10)\n  const actualEnd = Number.parseInt(match[2] ?? '', 10)\n  const actualTotal = match[3] ?? ''\n  if (actualStart !== start || actualEnd !== end) {\n    throw new RangeValidationError(\n      `Content-Range ${contentRange} does not match requested range ${start}-${end}`,\n    )\n  }\n\n  if (actualTotal === '*') {\n    throw new RangeValidationError(`Content-Range ${contentRange} does not include total size`)\n  }\n\n  const parsedTotal = Number.parseInt(actualTotal, 10)\n  if (parsedTotal !== totalSize) {\n    throw new RangeValidationError(\n      `Content-Range ${contentRange} does not match expected total size ${totalSize}`,\n    )\n  }\n\n  if (byteLength !== expectedLength) {\n    throw new RangeValidationError(\n      `Expected ${expectedLength} bytes for range ${start}-${end}, got ${byteLength}`,\n    )\n  }\n}\n\nasync function classifyDownloadResponseError(response: {\n  headers: Headers\n  status: number\n  body: ReadableStream<Uint8Array> | null\n}): Promise<B2Error> {\n  let errorBody: B2ErrorResponse = {\n    status: response.status,\n    code: 'internal_error',\n    message: `HTTP ${response.status}`,\n  }\n\n  if (response.body !== null) {\n    const bytes = await collectStream(response.body)\n    try {\n      const parsed = JSON.parse(utf8Decoder.decode(bytes)) as Partial<B2ErrorResponse>\n      errorBody = {\n        status: response.status,\n        code: parsed.code ?? 'internal_error',\n        message: parsed.message ?? `HTTP ${response.status}`,\n      }\n    } catch {\n      // Keep the synthetic errorBody above when the response body is not JSON.\n    }\n  }\n\n  const retryAfterHeader = response.headers.get('Retry-After')\n  const retryAfter = retryAfterHeader !== null ? Number.parseInt(retryAfterHeader, 10) : undefined\n  const requestId = response.headers.get('X-Bz-Request-Id') ?? undefined\n\n  return classifyError(errorBody, {\n    ...(retryAfter !== undefined ? { retryAfter } : {}),\n    ...(requestId !== undefined ? { requestId } : {}),\n  })\n}\n\nfunction isRetryableRangeError(err: unknown): boolean {\n  if (err instanceof B2Error || err instanceof NetworkError) return err.retryable\n  if (hasRetryableFlag(err)) return err.retryable\n  // Bare FetchTransport surfaces network failures as TypeError. Validation\n  // failures use RangeValidationError above, so they never land here.\n  return err instanceof TypeError\n}\n\nfunction hasRetryableFlag(err: unknown): err is { retryable: boolean } {\n  return (\n    typeof err === 'object' &&\n    err !== null &&\n    'retryable' in err &&\n    typeof (err as { retryable?: unknown }).retryable === 'boolean'\n  )\n}\n"],"mappings":"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"}
+{"version":3,"file":"parallel.js","names":[],"sources":["../../src/download/parallel.ts"],"sourcesContent":["import type { AccountInfo } from '../auth/account-info.ts'\nimport { B2Error, classifyError, NetworkError } from '../errors/index.ts'\nimport { computeBackoff, DEFAULT_RETRY_OPTIONS, type RetryOptions, sleep } from '../http/retry.ts'\nimport type { RawClient, SseCDownloadKey } from '../raw/index.ts'\nimport { collectStream } from '../streams/collect.ts'\nimport { IncrementalSha1 } from '../streams/hash.ts'\nimport { redactSseCKeyMaterial } from '../types/encryption.ts'\nimport type { B2ErrorResponse } from '../types/errors.ts'\nimport type { FileId } from '../types/ids.ts'\nimport { DEFAULT_DOWNLOAD_RANGE_SIZE, DEFAULT_TRANSFER_CONCURRENCY } from '../util/defaults.ts'\nimport { normalizeSha1 } from '../util/normalize.ts'\nimport { byteRangeHeader, planRanges } from '../util/plan-ranges.ts'\nimport { normalizeVerifiableSha1 } from '../util/sha1.ts'\nimport { utf8Decoder } from '../util/text-codec.ts'\nimport { assertDownloadSha1, assertDownloadSha1HeaderAgreement } from './checksum.ts'\n\n/** Options for downloading a file using concurrent byte-range requests. */\nexport interface ParallelDownloadOptions {\n  /** ID of the file to download. */\n  readonly fileId: FileId\n  /** Total file size in bytes (must be known in advance). */\n  readonly totalSize: number\n  /** Size of each ranged chunk in bytes. Defaults to 10 MB. */\n  readonly rangeSize?: number\n  /** Maximum number of chunks fetched in parallel. Defaults to 4. */\n  readonly concurrency?: number\n  /**\n   * SSE-C decryption parameters, required if the file was uploaded with SSE-C.\n   * Internal diagnostics redact the copied options object, but the key is still\n   * sent in plaintext SSE-C HTTP headers. Custom transports should not log\n   * request headers that may contain customer-provided keys.\n   */\n  readonly serverSideEncryption?: SseCDownloadKey\n  /**\n   * Extra retry attempts per range on transient failures. Defaults to 0 because\n   * `B2Client` already applies `RetryTransport`; set this only when supplying a\n   * raw client that does not already retry transport failures.\n   */\n  readonly maxRetries?: number\n  /** Signal to abort the download. */\n  readonly signal?: AbortSignal\n}\n\ninterface RangeDownloadResult {\n  readonly data: Uint8Array\n  readonly contentSha1: string | null\n}\n\ninterface FetchRangeWithRetryParams {\n  readonly raw: RawClient\n  readonly accountInfo: AccountInfo\n  readonly fileId: FileId\n  readonly start: number\n  readonly end: number\n  readonly totalSize: number\n  readonly serverSideEncryption: SseCDownloadKey | undefined\n  readonly retryOptions: RetryOptions\n  readonly signal: AbortSignal | undefined\n}\n\n/**\n * Creates a readable stream that downloads a file using parallel byte-range requests.\n *\n * The file is split into fixed-size ranges fetched in a **sliding\n * window** keyed off the consumer's read pace. The window size is\n * `concurrency * 2`: up to `concurrency` ranges are in flight at once,\n * plus up to `concurrency` completed-but-not-yet-emitted ranges buffered\n * ahead of the read head. New fetches kick off only when the consumer\n * reads a chunk, so a slow downstream pipe (e.g. a saturated network\n * sink or a `pipeTo` consumer that drains slowly) backpressures into\n * the SDK and bounds peak memory to `(concurrency * 2) * rangeSize`.\n *\n * The previous eager implementation scheduled every range into\n * `Promise.all` up front; a slow head-of-line range could hold the\n * entire file in memory while later ranges finished and waited.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param options - Parallel download parameters (file ID, size, concurrency).\n *\n * @returns A `ReadableStream` that yields file bytes in order.\n */\nexport function createParallelDownloadStream(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  options: ParallelDownloadOptions,\n): ReadableStream<Uint8Array> {\n  const rangeSize = options.rangeSize ?? DEFAULT_DOWNLOAD_RANGE_SIZE\n  const concurrency = options.concurrency ?? DEFAULT_TRANSFER_CONCURRENCY\n  const totalSize = options.totalSize\n  const serverSideEncryption =\n    options.serverSideEncryption !== undefined\n      ? redactSseCKeyMaterial(options.serverSideEncryption, { label: 'SseCDownloadKey' })\n      : undefined\n  // The high-level B2Client already wraps the raw transport in RetryTransport.\n  // Keep the parallel-download outer retry disabled by default so each range\n  // has one retry budget unless callers explicitly opt into an extra raw-client\n  // retry layer.\n  const retryOptions = {\n    ...DEFAULT_RETRY_OPTIONS,\n    maxRetries: options.maxRetries ?? 0,\n  }\n  const internalAbort = new AbortController()\n  const abort = internalAbort.signal\n  let removeCallerAbortListener: (() => void) | undefined\n  if (options.signal !== undefined) {\n    if (options.signal.aborted) {\n      internalAbort.abort(options.signal.reason)\n    } else {\n      const callerSignal = options.signal\n      const abortFromCaller = () => internalAbort.abort(callerSignal.reason)\n      callerSignal.addEventListener('abort', abortFromCaller, { once: true })\n      removeCallerAbortListener = () => callerSignal.removeEventListener('abort', abortFromCaller)\n    }\n  }\n\n  const ranges = planRanges(totalSize, rangeSize)\n\n  // `inflight` holds currently-fetching range promises; `buffer` holds\n  // completed ranges waiting for their slot in the emit order. Total\n  // scheduled-but-not-emitted = inflight.size + buffer.size is capped\n  // at `windowSize`, so peak memory is bounded regardless of any\n  // single range's latency.\n  const windowSize = concurrency * 2\n  const inflight = new Map<number, Promise<void>>()\n  const buffer = new Map<number, RangeDownloadResult>()\n  let assembledSha1: IncrementalSha1 | null = null\n  let nextToSchedule = 0\n  let nextToEmit = 0\n  let expectedSha1: string | null | undefined\n  let firstError: unknown = null\n\n  function abortInflight(reason?: unknown): void {\n    if (!abort.aborted) internalAbort.abort(reason)\n  }\n\n  function cleanupCallerAbortListener(): void {\n    removeCallerAbortListener?.()\n    removeCallerAbortListener = undefined\n  }\n\n  function scheduleNext(): void {\n    while (\n      firstError === null &&\n      // Honour abort here so a completed range that triggers a top-up\n      // doesn't queue one final fetch after the caller aborted. Without\n      // this gate, one extra range request fires post-abort before the\n      // `pull()` loop notices.\n      abort?.aborted !== true &&\n      nextToSchedule < ranges.length &&\n      inflight.size + buffer.size < windowSize\n    ) {\n      const range = ranges[nextToSchedule]\n      if (range === undefined) break\n      const idx = nextToSchedule\n      nextToSchedule++\n      const task = (async () => {\n        try {\n          const result = await fetchRangeWithRetry({\n            raw,\n            accountInfo,\n            fileId: options.fileId,\n            start: range.start,\n            end: range.end,\n            totalSize,\n            serverSideEncryption,\n            retryOptions,\n            signal: abort,\n          })\n          buffer.set(idx, result)\n        } catch (err) {\n          if (firstError === null) {\n            firstError = err\n            abortInflight(err)\n          }\n        } finally {\n          inflight.delete(idx)\n        }\n      })()\n      inflight.set(idx, task)\n    }\n  }\n\n  return new ReadableStream<Uint8Array>({\n    start(controller) {\n      // Pre-warm: kick off the initial window so the first `pull` has\n      // something to await. An already-aborted signal surfaces as a\n      // stream error rather than a synchronous throw, matching the\n      // contract callers had with the previous eager implementation.\n      try {\n        abort?.throwIfAborted()\n        scheduleNext()\n      } catch (err) {\n        cleanupCallerAbortListener()\n        controller.error(err)\n      }\n    },\n    async pull(controller) {\n      try {\n        // Wait until the next in-order chunk is available.\n        while (!buffer.has(nextToEmit)) {\n          abort?.throwIfAborted()\n          if (firstError !== null) throw firstError\n          // Zero-byte downloads have no planned ranges and close here. For\n          // non-empty downloads, this guard prevents a future refactor from\n          // stalling the stream if it leaves both maps empty mid-stream.\n          if (inflight.size === 0) {\n            cleanupCallerAbortListener()\n            controller.close()\n            return\n          }\n          await Promise.race(inflight.values())\n        }\n\n        const result = buffer.get(nextToEmit)\n        if (result !== undefined) {\n          buffer.delete(nextToEmit)\n          nextToEmit++\n          const rangeSha1 = normalizeVerifiableSha1(result.contentSha1)\n          if (expectedSha1 === undefined) {\n            expectedSha1 = rangeSha1\n          } else {\n            // B2 range responses should agree on the same whole-file SHA-1;\n            // any value or presence change makes verification untrustworthy.\n            assertDownloadSha1HeaderAgreement(expectedSha1, rangeSha1)\n          }\n          if (expectedSha1 !== null) {\n            assembledSha1 ??= new IncrementalSha1()\n            await assembledSha1.update(result.data)\n          }\n          controller.enqueue(result.data)\n        }\n\n        // Top up the window now that we freed a slot by emitting.\n        scheduleNext()\n\n        if (\n          nextToEmit >= ranges.length &&\n          buffer.size === 0 &&\n          inflight.size === 0 &&\n          firstError === null\n        ) {\n          if (expectedSha1 !== undefined && expectedSha1 !== null && assembledSha1 !== null) {\n            assertDownloadSha1(expectedSha1, await assembledSha1.digest())\n          }\n          cleanupCallerAbortListener()\n          controller.close()\n        }\n      } catch (err) {\n        abortInflight(err)\n        cleanupCallerAbortListener()\n        controller.error(err)\n      }\n    },\n    cancel(reason) {\n      abortInflight(reason)\n      cleanupCallerAbortListener()\n      // Abort propagation handles in-flight requests; just drop buffered\n      // data so it can be GC'd promptly.\n      buffer.clear()\n    },\n  })\n}\n\n/**\n * Fetches a single byte range with bounded retry on transient failures.\n * @param params - Range request parameters, retry settings, and cancellation.\n *\n * @returns The range's bytes, or throws after exhausting all retry attempts.\n */\nasync function fetchRangeWithRetry(\n  params: FetchRangeWithRetryParams,\n): Promise<RangeDownloadResult> {\n  const {\n    raw,\n    accountInfo,\n    fileId,\n    start,\n    end,\n    totalSize,\n    serverSideEncryption,\n    retryOptions,\n    signal,\n  } = params\n  let lastError: unknown\n  for (let attempt = 0; attempt <= retryOptions.maxRetries; attempt++) {\n    if (attempt > 0) {\n      const retryAfter =\n        lastError instanceof B2Error && lastError.retryAfter !== undefined\n          ? lastError.retryAfter\n          : undefined\n      const delay = computeBackoff(attempt - 1, retryOptions, retryAfter)\n      await sleep(delay, signal)\n    }\n    try {\n      signal?.throwIfAborted()\n      const resp = await raw.downloadFileById(\n        accountInfo.getDownloadUrl(),\n        accountInfo.getAuthToken(),\n        fileId,\n        {\n          range: byteRangeHeader(start, end),\n          ...(serverSideEncryption !== undefined ? { serverSideEncryption } : {}),\n          ...(signal !== undefined ? { signal } : {}),\n        },\n      )\n      if (resp.status < 200 || resp.status >= 300) {\n        throw await classifyDownloadResponseError(resp)\n      }\n      if (!resp.body) throw new Error('Download chunk has no body')\n      const data = await collectStream(resp.body)\n      validateRangeResponse(resp, start, end, totalSize, data.byteLength)\n      return {\n        data,\n        contentSha1: normalizeSha1(resp.headers.get('X-Bz-Content-Sha1')),\n      }\n    } catch (err) {\n      lastError = err\n      // Honour AbortSignal cancellation: don't retry past an abort.\n      if (signal?.aborted) throw err\n      if (err instanceof DOMException && err.name === 'AbortError') throw err\n      if (!isRetryableRangeError(err) || attempt === retryOptions.maxRetries) {\n        throw err\n      }\n    }\n  }\n  throw lastError instanceof Error ? lastError : new Error('Range download failed after retries')\n}\n\nclass RangeValidationError extends Error {\n  readonly retryable = false\n\n  constructor(message: string) {\n    super(message)\n    this.name = 'RangeValidationError'\n  }\n}\n\nfunction validateRangeResponse(\n  response: { headers: Headers; status: number },\n  start: number,\n  end: number,\n  totalSize: number,\n  byteLength: number,\n): void {\n  const expectedLength = end - start + 1\n  if (response.status !== 206) {\n    throw new RangeValidationError(\n      `Expected HTTP 206 Partial Content for range ${start}-${end}, got ${response.status}`,\n    )\n  }\n\n  const contentRange = response.headers.get('Content-Range')\n  if (contentRange === null) {\n    throw new RangeValidationError(`Missing Content-Range for range ${start}-${end}`)\n  }\n\n  const match = contentRange.match(/^bytes (\\d+)-(\\d+)\\/(\\d+|\\*)$/)\n  if (match === null) {\n    throw new RangeValidationError(\n      `Invalid Content-Range for range ${start}-${end}: ${contentRange}`,\n    )\n  }\n\n  const actualStart = Number.parseInt(match[1] ?? '', 10)\n  const actualEnd = Number.parseInt(match[2] ?? '', 10)\n  const actualTotal = match[3] ?? ''\n  if (actualStart !== start || actualEnd !== end) {\n    throw new RangeValidationError(\n      `Content-Range ${contentRange} does not match requested range ${start}-${end}`,\n    )\n  }\n\n  if (actualTotal === '*') {\n    throw new RangeValidationError(`Content-Range ${contentRange} does not include total size`)\n  }\n\n  const parsedTotal = Number.parseInt(actualTotal, 10)\n  if (parsedTotal !== totalSize) {\n    throw new RangeValidationError(\n      `Content-Range ${contentRange} does not match expected total size ${totalSize}`,\n    )\n  }\n\n  if (byteLength !== expectedLength) {\n    throw new RangeValidationError(\n      `Expected ${expectedLength} bytes for range ${start}-${end}, got ${byteLength}`,\n    )\n  }\n}\n\nasync function classifyDownloadResponseError(response: {\n  headers: Headers\n  status: number\n  body: ReadableStream<Uint8Array> | null\n}): Promise<B2Error> {\n  let errorBody: B2ErrorResponse = {\n    status: response.status,\n    code: 'internal_error',\n    message: `HTTP ${response.status}`,\n  }\n\n  if (response.body !== null) {\n    const bytes = await collectStream(response.body)\n    try {\n      const parsed = JSON.parse(utf8Decoder.decode(bytes)) as Partial<B2ErrorResponse>\n      errorBody = {\n        status: response.status,\n        code: parsed.code ?? 'internal_error',\n        message: parsed.message ?? `HTTP ${response.status}`,\n      }\n    } catch {\n      // Keep the synthetic errorBody above when the response body is not JSON.\n    }\n  }\n\n  const retryAfterHeader = response.headers.get('Retry-After')\n  const retryAfter = retryAfterHeader !== null ? Number.parseInt(retryAfterHeader, 10) : undefined\n  const requestId = response.headers.get('X-Bz-Request-Id') ?? undefined\n\n  return classifyError(errorBody, {\n    ...(retryAfter !== undefined ? { retryAfter } : {}),\n    ...(requestId !== undefined ? { requestId } : {}),\n  })\n}\n\nfunction isRetryableRangeError(err: unknown): boolean {\n  if (err instanceof B2Error || err instanceof NetworkError) return err.retryable\n  if (hasRetryableFlag(err)) return err.retryable\n  // Bare FetchTransport surfaces network failures as TypeError. Validation\n  // failures use RangeValidationError above, so they never land here.\n  return err instanceof TypeError\n}\n\nfunction hasRetryableFlag(err: unknown): err is { retryable: boolean } {\n  return (\n    typeof err === 'object' &&\n    err !== null &&\n    'retryable' in err &&\n    typeof (err as { retryable?: unknown }).retryable === 'boolean'\n  )\n}\n"],"mappings":"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"}