@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/download/checksum.cjs

@@ -0,0 +1,89 @@
+const require_errors_index = require("../errors/index.cjs");
+const require_hash = require("../streams/hash.cjs");
+const require_sha1 = require("../util/sha1.cjs");
+//#region src/download/checksum.ts
+/**
+* Client-side checksum helpers for download streams.
+*
+* B2 sends `X-Bz-Content-Sha1` on download responses when a whole-file
+* checksum is available. These helpers verify streamed bytes against that
+* header without buffering the full response in memory.
+*
+* @packageDocumentation
+*/
+/**
+* Builds the typed error used when downloaded bytes fail SHA-1 verification.
+*
+* @param expectedSha1 - SHA-1 digest advertised by the download response.
+* @param actualSha1 - SHA-1 digest computed from the downloaded bytes.
+*
+* @returns A typed checksum mismatch error.
+*/
+function createDownloadChecksumMismatchError(expectedSha1, actualSha1) {
+	return new require_errors_index.ChecksumMismatchError({
+		status: 400,
+		code: "bad_sha1_checksum",
+		message: `Downloaded content SHA-1 mismatch: expected ${expectedSha1.toLowerCase()}, got ${actualSha1.toLowerCase()}`
+	});
+}
+/**
+* Throws when a computed download SHA-1 does not match the expected value.
+*
+* @param expectedSha1 - SHA-1 digest advertised by the download response.
+* @param actualSha1 - SHA-1 digest computed from the downloaded bytes.
+*
+* @throws ChecksumMismatchError when the two digests differ.
+*/
+function assertDownloadSha1(expectedSha1, actualSha1) {
+	if (actualSha1.toLowerCase() !== expectedSha1.toLowerCase()) throw createDownloadChecksumMismatchError(expectedSha1, actualSha1);
+}
+/**
+* Throws when two range responses disagree about the expected whole-file SHA-1.
+*
+* @param expectedSha1 - The first range's verifiable SHA-1, or null when unavailable.
+* @param actualSha1 - The current range's verifiable SHA-1, or null when unavailable.
+*
+* @throws ChecksumMismatchError when the two header states differ.
+*/
+function assertDownloadSha1HeaderAgreement(expectedSha1, actualSha1) {
+	if (expectedSha1 === actualSha1) return;
+	throw new require_errors_index.ChecksumMismatchError({
+		status: 400,
+		code: "bad_sha1_checksum",
+		message: `Downloaded content SHA-1 header mismatch: expected ${formatSha1ForMessage(expectedSha1)}, got ${formatSha1ForMessage(actualSha1)}`
+	});
+}
+/**
+* Wraps a download stream with whole-body SHA-1 verification.
+*
+* If B2 did not provide a verifiable whole-file SHA-1 (for example,
+* multipart-finished files report `none`), the original stream is returned.
+*
+* @param body - Download response body.
+* @param expectedSha1 - Normalized SHA-1 header value, or null when unavailable.
+*
+* @returns A stream that emits the same bytes and errors on checksum mismatch.
+*/
+function verifyDownloadStream(body, expectedSha1) {
+	if (!require_sha1.isVerifiableSha1(expectedSha1)) return body;
+	const sha1 = new require_hash.IncrementalSha1();
+	const transform = new TransformStream({
+		async transform(chunk, controller) {
+			await sha1.update(chunk);
+			controller.enqueue(chunk);
+		},
+		async flush() {
+			assertDownloadSha1(expectedSha1, await sha1.digest());
+		}
+	});
+	return body.pipeThrough(transform);
+}
+function formatSha1ForMessage(sha1) {
+	return sha1 === null ? "missing or unverifiable" : sha1.toLowerCase();
+}
+//#endregion
+exports.assertDownloadSha1 = assertDownloadSha1;
+exports.assertDownloadSha1HeaderAgreement = assertDownloadSha1HeaderAgreement;
+exports.verifyDownloadStream = verifyDownloadStream;
+
+//# sourceMappingURL=checksum.cjs.map

package/dist/download/checksum.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"checksum.cjs","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,qBAAA,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,qBAAA,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,aAAA,iBAAiB,YAAY,GAAG,OAAO;CAE5C,MAAM,OAAO,IAAI,aAAA,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/checksum.d.cts

@@ -0,0 +1,40 @@
+/**
+ * Client-side checksum helpers for download streams.
+ *
+ * B2 sends `X-Bz-Content-Sha1` on download responses when a whole-file
+ * checksum is available. These helpers verify streamed bytes against that
+ * header without buffering the full response in memory.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Throws when a computed download SHA-1 does not match the expected value.
+ *
+ * @param expectedSha1 - SHA-1 digest advertised by the download response.
+ * @param actualSha1 - SHA-1 digest computed from the downloaded bytes.
+ *
+ * @throws ChecksumMismatchError when the two digests differ.
+ */
+export declare function assertDownloadSha1(expectedSha1: string, actualSha1: string): void;
+/**
+ * Throws when two range responses disagree about the expected whole-file SHA-1.
+ *
+ * @param expectedSha1 - The first range's verifiable SHA-1, or null when unavailable.
+ * @param actualSha1 - The current range's verifiable SHA-1, or null when unavailable.
+ *
+ * @throws ChecksumMismatchError when the two header states differ.
+ */
+export declare function assertDownloadSha1HeaderAgreement(expectedSha1: string | null, actualSha1: string | null): void;
+/**
+ * Wraps a download stream with whole-body SHA-1 verification.
+ *
+ * If B2 did not provide a verifiable whole-file SHA-1 (for example,
+ * multipart-finished files report `none`), the original stream is returned.
+ *
+ * @param body - Download response body.
+ * @param expectedSha1 - Normalized SHA-1 header value, or null when unavailable.
+ *
+ * @returns A stream that emits the same bytes and errors on checksum mismatch.
+ */
+export declare function verifyDownloadStream(body: ReadableStream<Uint8Array>, expectedSha1: string | null): ReadableStream<Uint8Array>;
+//# sourceMappingURL=checksum.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checksum.d.ts","sourceRoot":"","sources":["../../src/download/checksum.js"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA2BH;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAIjF;AAED;;;;;;;GAOG;AACH,wBAAgB,iCAAiC,CAC/C,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,IAAI,CASN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,YAAY,EAAE,MAAM,GAAG,IAAI,GAC1B,cAAc,CAAC,UAAU,CAAC,CAc5B"}

package/dist/download/checksum.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Client-side checksum helpers for download streams.
+ *
+ * B2 sends `X-Bz-Content-Sha1` on download responses when a whole-file
+ * checksum is available. These helpers verify streamed bytes against that
+ * header without buffering the full response in memory.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Throws when a computed download SHA-1 does not match the expected value.
+ *
+ * @param expectedSha1 - SHA-1 digest advertised by the download response.
+ * @param actualSha1 - SHA-1 digest computed from the downloaded bytes.
+ *
+ * @throws ChecksumMismatchError when the two digests differ.
+ */
+export declare function assertDownloadSha1(expectedSha1: string, actualSha1: string): void;
+/**
+ * Throws when two range responses disagree about the expected whole-file SHA-1.
+ *
+ * @param expectedSha1 - The first range's verifiable SHA-1, or null when unavailable.
+ * @param actualSha1 - The current range's verifiable SHA-1, or null when unavailable.
+ *
+ * @throws ChecksumMismatchError when the two header states differ.
+ */
+export declare function assertDownloadSha1HeaderAgreement(expectedSha1: string | null, actualSha1: string | null): void;
+/**
+ * Wraps a download stream with whole-body SHA-1 verification.
+ *
+ * If B2 did not provide a verifiable whole-file SHA-1 (for example,
+ * multipart-finished files report `none`), the original stream is returned.
+ *
+ * @param body - Download response body.
+ * @param expectedSha1 - Normalized SHA-1 header value, or null when unavailable.
+ *
+ * @returns A stream that emits the same bytes and errors on checksum mismatch.
+ */
+export declare function verifyDownloadStream(body: ReadableStream<Uint8Array>, expectedSha1: string | null): ReadableStream<Uint8Array>;
+//# sourceMappingURL=checksum.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checksum.d.ts","sourceRoot":"","sources":["../../src/download/checksum.js"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA2BH;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAIjF;AAED;;;;;;;GAOG;AACH,wBAAgB,iCAAiC,CAC/C,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,IAAI,CASN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,YAAY,EAAE,MAAM,GAAG,IAAI,GAC1B,cAAc,CAAC,UAAU,CAAC,CAc5B"}

package/dist/download/checksum.js

@@ -0,0 +1,87 @@
+import { ChecksumMismatchError } from "../errors/index.js";
+import { IncrementalSha1 } from "../streams/hash.js";
+import { isVerifiableSha1 } from "../util/sha1.js";
+//#region src/download/checksum.ts
+/**
+* Client-side checksum helpers for download streams.
+*
+* B2 sends `X-Bz-Content-Sha1` on download responses when a whole-file
+* checksum is available. These helpers verify streamed bytes against that
+* header without buffering the full response in memory.
+*
+* @packageDocumentation
+*/
+/**
+* Builds the typed error used when downloaded bytes fail SHA-1 verification.
+*
+* @param expectedSha1 - SHA-1 digest advertised by the download response.
+* @param actualSha1 - SHA-1 digest computed from the downloaded bytes.
+*
+* @returns A typed checksum mismatch error.
+*/
+function createDownloadChecksumMismatchError(expectedSha1, actualSha1) {
+	return new ChecksumMismatchError({
+		status: 400,
+		code: "bad_sha1_checksum",
+		message: `Downloaded content SHA-1 mismatch: expected ${expectedSha1.toLowerCase()}, got ${actualSha1.toLowerCase()}`
+	});
+}
+/**
+* Throws when a computed download SHA-1 does not match the expected value.
+*
+* @param expectedSha1 - SHA-1 digest advertised by the download response.
+* @param actualSha1 - SHA-1 digest computed from the downloaded bytes.
+*
+* @throws ChecksumMismatchError when the two digests differ.
+*/
+function assertDownloadSha1(expectedSha1, actualSha1) {
+	if (actualSha1.toLowerCase() !== expectedSha1.toLowerCase()) throw createDownloadChecksumMismatchError(expectedSha1, actualSha1);
+}
+/**
+* Throws when two range responses disagree about the expected whole-file SHA-1.
+*
+* @param expectedSha1 - The first range's verifiable SHA-1, or null when unavailable.
+* @param actualSha1 - The current range's verifiable SHA-1, or null when unavailable.
+*
+* @throws ChecksumMismatchError when the two header states differ.
+*/
+function assertDownloadSha1HeaderAgreement(expectedSha1, actualSha1) {
+	if (expectedSha1 === actualSha1) return;
+	throw new ChecksumMismatchError({
+		status: 400,
+		code: "bad_sha1_checksum",
+		message: `Downloaded content SHA-1 header mismatch: expected ${formatSha1ForMessage(expectedSha1)}, got ${formatSha1ForMessage(actualSha1)}`
+	});
+}
+/**
+* Wraps a download stream with whole-body SHA-1 verification.
+*
+* If B2 did not provide a verifiable whole-file SHA-1 (for example,
+* multipart-finished files report `none`), the original stream is returned.
+*
+* @param body - Download response body.
+* @param expectedSha1 - Normalized SHA-1 header value, or null when unavailable.
+*
+* @returns A stream that emits the same bytes and errors on checksum mismatch.
+*/
+function verifyDownloadStream(body, expectedSha1) {
+	if (!isVerifiableSha1(expectedSha1)) return body;
+	const sha1 = new IncrementalSha1();
+	const transform = new TransformStream({
+		async transform(chunk, controller) {
+			await sha1.update(chunk);
+			controller.enqueue(chunk);
+		},
+		async flush() {
+			assertDownloadSha1(expectedSha1, await sha1.digest());
+		}
+	});
+	return body.pipeThrough(transform);
+}
+function formatSha1ForMessage(sha1) {
+	return sha1 === null ? "missing or unverifiable" : sha1.toLowerCase();
+}
+//#endregion
+export { assertDownloadSha1, assertDownloadSha1HeaderAgreement, verifyDownloadStream };
+
+//# sourceMappingURL=checksum.js.map

package/dist/download/checksum.js.map

@@ -0,0 +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"}

package/dist/download/parallel.cjs

@@ -1,122 +1,218 @@
-"use strict";
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const retry = require("../http/retry.cjs");
-const collect = require("../streams/collect.cjs");
-const defaults = require("../util/defaults.cjs");
-const planRanges = require("../util/plan-ranges.cjs");
+const require_errors_index = require("../errors/index.cjs");
+const require_plan_ranges = require("../util/plan-ranges.cjs");
+const require_text_codec = require("../util/text-codec.cjs");
+const require_normalize = require("../util/normalize.cjs");
+const require_hash = require("../streams/hash.cjs");
+const require_sha1 = require("../util/sha1.cjs");
+const require_checksum = require("./checksum.cjs");
+const require_retry = require("../http/retry.cjs");
+const require_collect = require("../streams/collect.cjs");
+//#region src/download/parallel.ts
+/**
+* Creates a readable stream that downloads a file using parallel byte-range requests.
+*
+* The file is split into fixed-size ranges fetched in a **sliding
+* window** keyed off the consumer's read pace. The window size is
+* `concurrency * 2`: up to `concurrency` ranges are in flight at once,
+* plus up to `concurrency` completed-but-not-yet-emitted ranges buffered
+* ahead of the read head. New fetches kick off only when the consumer
+* reads a chunk, so a slow downstream pipe (e.g. a saturated network
+* sink or a `pipeTo` consumer that drains slowly) backpressures into
+* the SDK and bounds peak memory to `(concurrency * 2) * rangeSize`.
+*
+* The previous eager implementation scheduled every range into
+* `Promise.all` up front; a slow head-of-line range could hold the
+* entire file in memory while later ranges finished and waited.
+*
+* @param raw - Low-level B2 API client.
+* @param accountInfo - Authorized account state.
+* @param options - Parallel download parameters (file ID, size, concurrency).
+*
+* @returns A `ReadableStream` that yields file bytes in order.
+*/
 function createParallelDownloadStream(raw, accountInfo, options) {
-  const rangeSize = options.rangeSize ?? 10 * 1024 * 1024;
-  const concurrency = options.concurrency ?? defaults.DEFAULT_TRANSFER_CONCURRENCY;
-  const totalSize = options.totalSize;
-  const retryOptions = {
-    ...retry.DEFAULT_RETRY_OPTIONS,
-    ...options.maxRetries !== void 0 ? { maxRetries: options.maxRetries } : {}
-  };
-  const abort = options.signal;
-  const ranges = planRanges.planRanges(totalSize, rangeSize);
-  const windowSize = concurrency * 2;
-  const inflight = /* @__PURE__ */ new Map();
-  const buffer = /* @__PURE__ */ new Map();
-  let nextToSchedule = 0;
-  let nextToEmit = 0;
-  let firstError = null;
-  function scheduleNext() {
-    while (firstError === null && // Honour abort here so a completed range that triggers a top-up
-    // doesn't queue one final fetch after the caller aborted. Without
-    // this gate, one extra range request fires post-abort before the
-    // `pull()` loop notices.
-    abort?.aborted !== true && nextToSchedule < ranges.length && inflight.size + buffer.size < windowSize) {
-      const range = ranges[nextToSchedule];
-      if (range === void 0) break;
-      const idx = nextToSchedule;
-      nextToSchedule++;
-      const task = (async () => {
-        try {
-          const data = await fetchRangeWithRetry(
-            raw,
-            accountInfo,
-            options.fileId,
-            range.start,
-            range.end,
-            retryOptions,
-            abort
-          );
-          buffer.set(idx, data);
-        } catch (err) {
-          if (firstError === null) firstError = err;
-        } finally {
-          inflight.delete(idx);
-        }
-      })();
-      inflight.set(idx, task);
-    }
-  }
-  return new ReadableStream({
-    start(controller) {
-      try {
-        abort?.throwIfAborted();
-        scheduleNext();
-      } catch (err) {
-        controller.error(err);
-      }
-    },
-    async pull(controller) {
-      try {
-        while (!buffer.has(nextToEmit)) {
-          abort?.throwIfAborted();
-          if (firstError !== null) throw firstError;
-          if (inflight.size === 0) {
-            controller.close();
-            return;
-          }
-          await Promise.race(inflight.values());
-        }
-        const data = buffer.get(nextToEmit);
-        if (data !== void 0) {
-          buffer.delete(nextToEmit);
-          nextToEmit++;
-          controller.enqueue(data);
-        }
-        scheduleNext();
-        if (nextToEmit >= ranges.length && buffer.size === 0 && inflight.size === 0 && firstError === null) {
-          controller.close();
-        }
-      } catch (err) {
-        controller.error(err);
-      }
-    },
-    cancel() {
-      buffer.clear();
-    }
-  });
+	const rangeSize = options.rangeSize ?? 10 * 1024 * 1024;
+	const concurrency = options.concurrency ?? 4;
+	const totalSize = options.totalSize;
+	const retryOptions = {
+		...require_retry.DEFAULT_RETRY_OPTIONS,
+		maxRetries: options.maxRetries ?? 0
+	};
+	const abort = options.signal;
+	const ranges = require_plan_ranges.planRanges(totalSize, rangeSize);
+	const windowSize = concurrency * 2;
+	const inflight = /* @__PURE__ */ new Map();
+	const buffer = /* @__PURE__ */ new Map();
+	let assembledSha1 = null;
+	let nextToSchedule = 0;
+	let nextToEmit = 0;
+	let expectedSha1;
+	let firstError = null;
+	function scheduleNext() {
+		while (firstError === null && abort?.aborted !== true && nextToSchedule < ranges.length && inflight.size + buffer.size < windowSize) {
+			const range = ranges[nextToSchedule];
+			if (range === void 0) break;
+			const idx = nextToSchedule;
+			nextToSchedule++;
+			const task = (async () => {
+				try {
+					const result = await fetchRangeWithRetry(raw, accountInfo, options.fileId, range.start, range.end, totalSize, retryOptions, abort);
+					buffer.set(idx, result);
+				} catch (err) {
+					if (firstError === null) firstError = err;
+				} finally {
+					inflight.delete(idx);
+				}
+			})();
+			inflight.set(idx, task);
+		}
+	}
+	return new ReadableStream({
+		start(controller) {
+			try {
+				abort?.throwIfAborted();
+				scheduleNext();
+			} catch (err) {
+				controller.error(err);
+			}
+		},
+		async pull(controller) {
+			try {
+				while (!buffer.has(nextToEmit)) {
+					abort?.throwIfAborted();
+					if (firstError !== null) throw firstError;
+					if (inflight.size === 0) {
+						controller.close();
+						return;
+					}
+					await Promise.race(inflight.values());
+				}
+				const result = buffer.get(nextToEmit);
+				if (result !== void 0) {
+					buffer.delete(nextToEmit);
+					nextToEmit++;
+					const rangeSha1 = require_sha1.normalizeVerifiableSha1(result.contentSha1);
+					if (expectedSha1 === void 0) expectedSha1 = rangeSha1;
+					else require_checksum.assertDownloadSha1HeaderAgreement(expectedSha1, rangeSha1);
+					if (expectedSha1 !== null) {
+						assembledSha1 ??= new require_hash.IncrementalSha1();
+						await assembledSha1.update(result.data);
+					}
+					controller.enqueue(result.data);
+				}
+				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());
+					controller.close();
+				}
+			} catch (err) {
+				controller.error(err);
+			}
+		},
+		cancel() {
+			buffer.clear();
+		}
+	});
 }
-async function fetchRangeWithRetry(raw, accountInfo, fileId, start, end, retryOptions, signal) {
-  let lastError;
-  for (let attempt = 0; attempt <= retryOptions.maxRetries; attempt++) {
-    if (attempt > 0) {
-      const delay = retry.computeBackoff(attempt - 1, retryOptions);
-      await retry.sleep(delay, signal);
-    }
-    try {
-      signal?.throwIfAborted();
-      const resp = await raw.downloadFileById(
-        accountInfo.getDownloadUrl(),
-        accountInfo.getAuthToken(),
-        fileId,
-        {
-          range: planRanges.byteRangeHeader(start, end),
-          ...signal !== void 0 ? { signal } : {}
-        }
-      );
-      if (!resp.body) throw new Error("Download chunk has no body");
-      return await collect.collectStream(resp.body);
-    } catch (err) {
-      lastError = err;
-      if (signal?.aborted) throw err;
-      if (err instanceof DOMException && err.name === "AbortError") throw err;
-    }
-  }
-  throw lastError instanceof Error ? lastError : new Error("Range download failed after retries");
+/**
+* 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.
+*
+* @returns The range's bytes, or throws after exhausting all retry attempts.
+*/
+async function fetchRangeWithRetry(raw, accountInfo, fileId, start, end, totalSize, retryOptions, signal) {
+	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);
+		}
+		try {
+			signal?.throwIfAborted();
+			const resp = await raw.downloadFileById(accountInfo.getDownloadUrl(), accountInfo.getAuthToken(), fileId, {
+				range: require_plan_ranges.byteRangeHeader(start, end),
+				...signal !== void 0 ? { signal } : {}
+			});
+			if (resp.status < 200 || resp.status >= 300) throw await classifyDownloadResponseError(resp);
+			if (!resp.body) throw new Error("Download chunk has no body");
+			const data = await require_collect.collectStream(resp.body);
+			validateRangeResponse(resp, start, end, totalSize, data.byteLength);
+			return {
+				data,
+				contentSha1: require_normalize.normalizeSha1(resp.headers.get("X-Bz-Content-Sha1"))
+			};
+		} catch (err) {
+			lastError = err;
+			if (signal?.aborted) throw err;
+			if (err instanceof DOMException && err.name === "AbortError") throw err;
+			if (!isRetryableRangeError(err) || attempt === retryOptions.maxRetries) throw err;
+		}
+	}
+	throw lastError instanceof Error ? lastError : /* @__PURE__ */ new Error("Range download failed after retries");
 }
+var RangeValidationError = class extends Error {
+	retryable = false;
+	constructor(message) {
+		super(message);
+		this.name = "RangeValidationError";
+	}
+};
+function validateRangeResponse(response, start, end, totalSize, byteLength) {
+	const expectedLength = end - start + 1;
+	if (response.status !== 206) throw new RangeValidationError(`Expected HTTP 206 Partial Content for range ${start}-${end}, got ${response.status}`);
+	const contentRange = response.headers.get("Content-Range");
+	if (contentRange === null) throw new RangeValidationError(`Missing Content-Range for range ${start}-${end}`);
+	const match = contentRange.match(/^bytes (\d+)-(\d+)\/(\d+|\*)$/);
+	if (match === null) throw new RangeValidationError(`Invalid Content-Range for range ${start}-${end}: ${contentRange}`);
+	const actualStart = Number.parseInt(match[1] ?? "", 10);
+	const actualEnd = Number.parseInt(match[2] ?? "", 10);
+	const actualTotal = match[3] ?? "";
+	if (actualStart !== start || actualEnd !== end) throw new RangeValidationError(`Content-Range ${contentRange} does not match requested range ${start}-${end}`);
+	if (actualTotal === "*") throw new RangeValidationError(`Content-Range ${contentRange} does not include total size`);
+	if (Number.parseInt(actualTotal, 10) !== totalSize) throw new RangeValidationError(`Content-Range ${contentRange} does not match expected total size ${totalSize}`);
+	if (byteLength !== expectedLength) throw new RangeValidationError(`Expected ${expectedLength} bytes for range ${start}-${end}, got ${byteLength}`);
+}
+async function classifyDownloadResponseError(response) {
+	let errorBody = {
+		status: response.status,
+		code: "internal_error",
+		message: `HTTP ${response.status}`
+	};
+	if (response.body !== null) {
+		const bytes = await require_collect.collectStream(response.body);
+		try {
+			const parsed = JSON.parse(require_text_codec.utf8Decoder.decode(bytes));
+			errorBody = {
+				status: response.status,
+				code: parsed.code ?? "internal_error",
+				message: parsed.message ?? `HTTP ${response.status}`
+			};
+		} catch {}
+	}
+	const retryAfterHeader = response.headers.get("Retry-After");
+	const retryAfter = retryAfterHeader !== null ? Number.parseInt(retryAfterHeader, 10) : void 0;
+	const requestId = response.headers.get("X-Bz-Request-Id") ?? void 0;
+	return require_errors_index.classifyError(errorBody, {
+		...retryAfter !== void 0 ? { retryAfter } : {},
+		...requestId !== void 0 ? { requestId } : {}
+	});
+}
+function isRetryableRangeError(err) {
+	if (err instanceof require_errors_index.B2Error || err instanceof require_errors_index.NetworkError) return err.retryable;
+	if (hasRetryableFlag(err)) return err.retryable;
+	return err instanceof TypeError;
+}
+function hasRetryableFlag(err) {
+	return typeof err === "object" && err !== null && "retryable" in err && typeof err.retryable === "boolean";
+}
+//#endregion
 exports.createParallelDownloadStream = createParallelDownloadStream;
-//# sourceMappingURL=parallel.cjs.map
+
+//# sourceMappingURL=parallel.cjs.map