@backblaze-labs/b2-sdk 0.1.0 → 0.3.0

package/dist/sync/policies/compare.cjs

@@ -1,14 +1,394 @@
-"use strict";
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_concurrency = require("../../upload/concurrency.cjs");
+const require_abort = require("../../util/abort.cjs");
+const require_sha1 = require("../../util/sha1.cjs");
+const require_to_error = require("../../util/to-error.cjs");
+const require_local_sha1 = require("../local-sha1.cjs");
+const require_sha1_metadata = require("../sha1-metadata.cjs");
+//#region src/sync/policies/compare.ts
+/**
+* Determines whether two files should be considered different based on the compare mode.
+* For `sha1`, callers that use the low-level policy helpers should first prepare the pair so
+* local hashes and comparable B2 hashes are populated.
+*
+* @param source - The source file metadata.
+* @param dest - The destination file metadata.
+* @param compareMode - The comparison strategy: 'modtime', 'size', 'sha1', or 'none'.
+* @param threshold - Tolerance for the comparison (bytes for size, milliseconds for modtime).
+*
+* @returns `true` if the files are considered different.
+*
+* @throws When `compareMode` is not one of the supported compare modes.
+*/
 function filesAreDifferent(source, dest, compareMode, threshold = 0) {
-  switch (compareMode) {
-    case "none":
-      return false;
-    case "size":
-      return Math.abs(source.size - dest.size) > threshold;
-    case "modtime":
-      return Math.abs(source.modTimeMillis - dest.modTimeMillis) > threshold;
-  }
+	switch (compareMode) {
+		case "none": return false;
+		case "size": return Math.abs(source.size - dest.size) > threshold;
+		case "sha1": return sha1ValuesAreDifferent(source, dest);
+		case "modtime": return Math.abs(source.modTimeMillis - dest.modTimeMillis) > threshold;
+		default: throw new Error(`Unsupported compare mode: ${String(compareMode)}`);
+	}
 }
+/**
+* Throws when a runtime compare mode value is unsupported.
+*
+* @param compareMode - User-supplied compare mode.
+*
+* @throws When `compareMode` is not one of the supported values.
+*/
+function assertSupportedCompareMode(compareMode) {
+	switch (compareMode) {
+		case "none":
+		case "size":
+		case "sha1":
+		case "modtime": return;
+		default: throw new Error(`Unsupported compare mode: ${String(compareMode)}`);
+	}
+}
+function sha1ValuesAreDifferent(source, dest) {
+	if (source.size !== dest.size) return true;
+	const sourceSha1 = comparableSha1(source);
+	const destSha1 = comparableSha1(dest);
+	if (sourceSha1.kind === "untrusted" || destSha1.kind === "untrusted") return true;
+	if (sourceSha1.kind === "unavailable" || destSha1.kind === "unavailable") return true;
+	return sourceSha1.value !== destSha1.value;
+}
+/**
+* Prepares a pair for the selected compare mode.
+*
+* For `sha1`, this fills missing B2 hashes from comparable metadata and, when an explicit local
+* reader is supplied, hashes the local side only when size cannot already prove a difference.
+* Reader failures are converted into per-file sync events instead of aborting the whole run.
+*
+* @param pair - Source/destination pair from {@link zipFolders}.
+* @param compareMode - The comparison strategy.
+* @param options - Optional hashing dependencies and cancellation signal.
+*
+* @returns The prepared pair plus any preparation events.
+*/
+async function preparePairForCompare(pair, compareMode, options = {}) {
+	assertSupportedCompareMode(compareMode);
+	if (compareMode !== "sha1") return readyComparePair(pair);
+	const [source, dest] = pair;
+	if (source === null || dest === null) return readyComparePair(pair);
+	if (source.size !== dest.size) return readyComparePair(pair);
+	const metadataPair = [withB2ContentSha1(source), withB2ContentSha1(dest)];
+	if (hasUnavailableB2Sha1(metadataPair)) return skipped(metadataPair, unavailableSha1Event(metadataPair));
+	if (options.readB2Sha1 === void 0 && hasUntrustedSha1(metadataPair) && !hasVerifiableUntrustedSha1(metadataPair)) return readyComparePair(metadataPair);
+	const [metadataSource, metadataDest] = metadataPair;
+	if (metadataSource === null || metadataDest === null) return readyComparePair(metadataPair);
+	const sourceResult = await prepareLocalPathSha1(metadataSource, options);
+	if (sourceResult.aborted) return aborted(metadataPair);
+	if (sourceResult.event) return skipped(metadataPair, sourceResult.event, sourceResult.error, sourceResult.bytesHashed);
+	const destResult = await prepareLocalPathSha1(metadataDest, options);
+	if (destResult.aborted) return aborted([sourceResult.path, destResult.path]);
+	if (destResult.event) return skipped([sourceResult.path, destResult.path], destResult.event, destResult.error, sourceResult.bytesHashed);
+	const preparedPair = [sourceResult.path, destResult.path];
+	const sourceState = comparableSha1(sourceResult.path);
+	const destState = comparableSha1(destResult.path);
+	const bytesHashed = sourceResult.bytesHashed + destResult.bytesHashed;
+	if (sourceState.kind === "unavailable" || destState.kind === "unavailable") return skipped(preparedPair, unavailableSha1Event(preparedPair), void 0, bytesHashed);
+	const shouldVerifyB2Bytes = untrustedSha1CouldSuppressTransfer(sourceState, destState);
+	const readB2Sha1 = options.readB2Sha1;
+	if (shouldVerifyB2Bytes && hasB2Path(preparedPair) && readB2Sha1 !== void 0) return verifyB2Sha1Bytes(preparedPair, {
+		...options,
+		readB2Sha1
+	}, bytesHashed);
+	return readyComparePair(preparedPair, bytesHashed);
+}
+/**
+* Prepares a list of pairs for the selected compare mode with bounded concurrency.
+*
+* @param pairs - Source/destination pairs from {@link zipFolders}.
+* @param compareMode - The comparison strategy.
+* @param options - Optional hashing dependencies, cancellation signal, and concurrency.
+*
+* @returns Prepared results in the same order as the input pairs.
+*/
+async function preparePairsForCompare(pairs, compareMode, options = {}) {
+	assertSupportedCompareMode(compareMode);
+	if (compareMode !== "sha1") return pairs.map((pair) => ({
+		originalPair: pair,
+		prepared: readyComparePair(pair)
+	}));
+	const concurrency = normalizeConcurrency(options.concurrency);
+	return require_concurrency.mapConcurrent(pairs, concurrency, async (pair) => {
+		if (options.signal?.aborted) return {
+			originalPair: pair,
+			prepared: aborted(pair)
+		};
+		return {
+			originalPair: pair,
+			prepared: await preparePairForCompare(pair, compareMode, options)
+		};
+	});
+}
+async function prepareLocalPathSha1(path, options) {
+	if (!isLocalSyncPath(path)) return {
+		path,
+		bytesHashed: 0,
+		bytesVerified: 0,
+		aborted: false
+	};
+	if (options.signal?.aborted) return {
+		path,
+		bytesHashed: 0,
+		bytesVerified: 0,
+		aborted: true
+	};
+	try {
+		const state = require_sha1_metadata.syncSha1StateOf(path);
+		if (state.kind === "verified") return {
+			path: {
+				...path,
+				contentSha1: state.value
+			},
+			bytesHashed: 0,
+			bytesVerified: 0,
+			aborted: false
+		};
+		if (state.kind === "unavailable") return {
+			path: {
+				...path,
+				contentSha1: null
+			},
+			bytesHashed: 0,
+			bytesVerified: 0,
+			aborted: false
+		};
+		const readLocalSha1 = options.readLocalSha1;
+		if (readLocalSha1 === void 0) return {
+			path: {
+				...path,
+				contentSha1: path.contentSha1 ?? null
+			},
+			bytesHashed: 0,
+			bytesVerified: 0,
+			aborted: false
+		};
+		const contentSha1 = await readLocalSha1(path, options.signal, { ...options.sha1ReadTimeoutMillis !== void 0 ? { timeoutMillis: options.sha1ReadTimeoutMillis } : {} });
+		return {
+			path: {
+				...path,
+				contentSha1
+			},
+			bytesHashed: require_sha1.normalizeVerifiableSha1(contentSha1) === null ? 0 : path.size,
+			bytesVerified: 0,
+			aborted: false
+		};
+	} catch (err) {
+		if (require_abort.isSignalAbortError(options.signal, err)) return {
+			path,
+			bytesHashed: 0,
+			bytesVerified: 0,
+			aborted: true
+		};
+		const error = require_to_error.toError(err);
+		return {
+			path,
+			bytesHashed: 0,
+			event: {
+				type: "error",
+				path: path.relativePath,
+				size: 0,
+				message: `failed to hash local file for sha1 comparison: ${require_local_sha1.formatHashError(error)}`
+			},
+			error,
+			bytesVerified: 0,
+			aborted: false
+		};
+	}
+}
+async function verifyB2Sha1Bytes(pair, options, bytesHashed) {
+	const [source, dest] = pair;
+	/* v8 ignore next -- callers only verify B2 bytes for paired compare results */
+	if (source === null || dest === null) return readyComparePair(pair, bytesHashed);
+	const sourceResult = await prepareUntrustedB2PathSha1(source, options);
+	const sourceBytesVerified = sourceResult.bytesVerified;
+	if (sourceResult.aborted) return aborted(pair);
+	if (sourceResult.event) return skipped([sourceResult.path, dest], sourceResult.event, sourceResult.error, bytesHashed, sourceBytesVerified);
+	const destResult = await prepareUntrustedB2PathSha1(dest, options);
+	const bytesVerified = sourceBytesVerified + destResult.bytesVerified;
+	/* v8 ignore next -- destination abort mirrors the covered source abort path */
+	if (destResult.aborted) return aborted([sourceResult.path, destResult.path]);
+	if (destResult.event) return skipped([sourceResult.path, destResult.path], destResult.event, destResult.error, bytesHashed, bytesVerified);
+	return readyComparePair([sourceResult.path, destResult.path], bytesHashed, bytesVerified);
+}
+async function prepareUntrustedB2PathSha1(path, options) {
+	if (!isB2SyncPath(path) || comparableSha1(path).kind !== "untrusted") return {
+		path,
+		bytesHashed: 0,
+		bytesVerified: 0,
+		aborted: false
+	};
+	return prepareB2PathSha1(path, options);
+}
+async function prepareB2PathSha1(path, options) {
+	/* v8 ignore next -- pre-aborted B2 reads are covered at pair level */
+	if (options.signal?.aborted) return {
+		path,
+		bytesHashed: 0,
+		bytesVerified: 0,
+		aborted: true
+	};
+	try {
+		const result = await options.readB2Sha1(path, options.signal);
+		const contentSha1 = typeof result === "object" && result !== null ? result.contentSha1 : result;
+		const bytesVerified = typeof result === "object" && result !== null ? Math.max(0, result.bytesRead) : 0;
+		const preparedPath = {
+			...path,
+			contentSha1,
+			contentSha1State: require_sha1_metadata.syncSha1StateOf({ contentSha1 })
+		};
+		if (contentSha1 === null) return {
+			path: preparedPath,
+			bytesHashed: 0,
+			bytesVerified,
+			event: unavailableSha1PathEvent(path),
+			aborted: false
+		};
+		return {
+			path: preparedPath,
+			bytesHashed: 0,
+			bytesVerified,
+			aborted: false
+		};
+	} catch (err) {
+		if (require_abort.isSignalAbortError(options.signal, err)) return {
+			path,
+			bytesHashed: 0,
+			bytesVerified: 0,
+			aborted: true
+		};
+		const error = require_to_error.toError(err);
+		return {
+			path,
+			bytesHashed: 0,
+			bytesVerified: 0,
+			event: {
+				type: "skip",
+				path: path.relativePath,
+				size: 0,
+				message: `sha1 comparison skipped because B2 verification failed: ${require_local_sha1.formatHashError(error)}`
+			},
+			aborted: false
+		};
+	}
+}
+function comparableSha1(path) {
+	const state = require_sha1_metadata.syncSha1StateOf(path);
+	if (state.kind === "verified") return {
+		kind: "verified",
+		value: state.value
+	};
+	if (state.kind === "untrusted") return {
+		kind: "untrusted",
+		value: state.value
+	};
+	return { kind: "unavailable" };
+}
+function untrustedSha1CouldSuppressTransfer(source, dest) {
+	if (source.kind === "untrusted" && dest.kind === "verified") return source.value === dest.value;
+	if (dest.kind === "untrusted" && source.kind === "verified") return dest.value === source.value;
+	if (source.kind === "untrusted" && dest.kind === "untrusted") return source.value !== null && source.value === dest.value;
+	return false;
+}
+function withB2ContentSha1(path) {
+	if (!isB2SyncPath(path) || path.contentSha1 !== void 0 || path.contentSha1State !== void 0) return path;
+	const contentSha1 = require_sha1_metadata.selectB2ComparableSha1(path.selectedVersion);
+	return {
+		...path,
+		contentSha1,
+		contentSha1State: require_sha1_metadata.syncSha1StateOf({ contentSha1 })
+	};
+}
+function hasUnavailableB2Sha1(pair) {
+	const [source, dest] = pair;
+	return source !== null && isB2SyncPath(source) && comparableSha1(source).kind === "unavailable" || dest !== null && isB2SyncPath(dest) && comparableSha1(dest).kind === "unavailable";
+}
+function hasUntrustedSha1(pair) {
+	const [source, dest] = pair;
+	return source !== null && comparableSha1(source).kind === "untrusted" || dest !== null && comparableSha1(dest).kind === "untrusted";
+}
+function hasVerifiableUntrustedSha1(pair) {
+	const [source, dest] = pair;
+	return source !== null && verifiableUntrustedSha1(source) || dest !== null && verifiableUntrustedSha1(dest);
+}
+function verifiableUntrustedSha1(path) {
+	const state = comparableSha1(path);
+	return state.kind === "untrusted" && state.value !== null;
+}
+function hasB2Path(pair) {
+	const [source, dest] = pair;
+	return source !== null && isB2SyncPath(source) || dest !== null && isB2SyncPath(dest);
+}
+function isB2SyncPath(path) {
+	return "selectedVersion" in path;
+}
+function isLocalSyncPath(path) {
+	return "absolutePath" in path;
+}
+/**
+* Creates a successful no-op compare preparation result for a pair.
+*
+* @param pair - Source/destination pair from {@link zipFolders}.
+* @param bytesHashed - Local file bytes read while preparing the pair.
+* @param bytesVerified - B2 bytes read while verifying untrusted SHA-1 metadata.
+*
+* @returns A ready preparation result that allows action generation.
+*/
+function readyComparePair(pair, bytesHashed = 0, bytesVerified = 0) {
+	return {
+		pair,
+		events: [],
+		errors: [],
+		bytesHashed,
+		bytesVerified,
+		skipActionGeneration: false,
+		aborted: false
+	};
+}
+function skipped(pair, event, error, bytesHashed = 0, bytesVerified = 0) {
+	return {
+		pair,
+		events: [event],
+		errors: error !== void 0 ? [error] : [],
+		bytesHashed,
+		bytesVerified,
+		skipActionGeneration: true,
+		aborted: false
+	};
+}
+function aborted(pair) {
+	return {
+		pair,
+		events: [],
+		errors: [],
+		bytesHashed: 0,
+		bytesVerified: 0,
+		skipActionGeneration: true,
+		aborted: true
+	};
+}
+function unavailableSha1Event(pair) {
+	return unavailableSha1PathEvent({ relativePath: (pair[0] ?? pair[1])?.relativePath ?? "" });
+}
+function unavailableSha1PathEvent(path) {
+	return {
+		type: "skip",
+		path: path.relativePath,
+		size: 0,
+		message: "sha1 comparison skipped because a verifiable SHA-1 is unavailable"
+	};
+}
+function normalizeConcurrency(value) {
+	if (value === void 0 || !Number.isFinite(value) || value < 1) return 1;
+	return Math.max(1, Math.floor(value));
+}
+//#endregion
+exports.assertSupportedCompareMode = assertSupportedCompareMode;
 exports.filesAreDifferent = filesAreDifferent;
-//# sourceMappingURL=compare.cjs.map
+exports.preparePairForCompare = preparePairForCompare;
+exports.preparePairsForCompare = preparePairsForCompare;
+exports.readyComparePair = readyComparePair;
+
+//# sourceMappingURL=compare.cjs.map

package/dist/sync/policies/compare.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"compare.cjs","sources":["../../../src/sync/policies/compare.ts"],"sourcesContent":["import type { CompareMode, SyncPath } from '../types.ts'\n\n/**\n * Determines whether two files should be considered different based on the compare mode.\n *\n * @param source - The source file metadata.\n * @param dest - The destination file metadata.\n * @param compareMode - The comparison strategy: 'modtime', 'size', or 'none'.\n * @param threshold - Tolerance for the comparison (bytes for size, milliseconds for modtime).\n *\n * @returns `true` if the files are considered different.\n */\nexport function filesAreDifferent(\n  source: SyncPath,\n  dest: SyncPath,\n  compareMode: CompareMode,\n  threshold = 0,\n): boolean {\n  switch (compareMode) {\n    case 'none':\n      return false\n    case 'size':\n      return Math.abs(source.size - dest.size) > threshold\n    case 'modtime':\n      return Math.abs(source.modTimeMillis - dest.modTimeMillis) > threshold\n  }\n}\n"],"names":[],"mappings":";;AAYO,SAAS,kBACd,QACA,MACA,aACA,YAAY,GACH;AACT,UAAQ,aAAA;AAAA,IACN,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO,KAAK,IAAI,OAAO,OAAO,KAAK,IAAI,IAAI;AAAA,IAC7C,KAAK;AACH,aAAO,KAAK,IAAI,OAAO,gBAAgB,KAAK,aAAa,IAAI;AAAA,EAAA;AAEnE;;"}
+{"version":3,"file":"compare.cjs","names":[],"sources":["../../../src/sync/policies/compare.ts"],"sourcesContent":["import { mapConcurrent } from '../../upload/concurrency.ts'\nimport { isSignalAbortError } from '../../util/abort.ts'\nimport { normalizeVerifiableSha1 } from '../../util/sha1.ts'\nimport { toError } from '../../util/to-error.ts'\nimport { formatHashError, type LocalSha1Reader } from '../local-sha1.ts'\nimport type { SyncPair } from '../pairing.ts'\nimport { selectB2ComparableSha1, syncSha1StateOf } from '../sha1-metadata.ts'\nimport type {\n  B2SyncPath,\n  CompareMode,\n  LocalSyncPath,\n  SyncEvent,\n  SyncPath,\n  SyncSkipEvent,\n} from '../types.ts'\n\nexport { selectB2ComparableSha1 } from '../sha1-metadata.ts'\n\n/** Result from a B2 SHA-1 verification read. */\nexport interface B2Sha1ReadResult {\n  /** SHA-1 digest of the selected B2 bytes, or null when unavailable. */\n  readonly contentSha1: string | null\n  /** Number of B2 bytes downloaded and hashed while verifying. */\n  readonly bytesRead: number\n}\n\n/** Reads a B2 file and returns the SHA-1 digest of its actual bytes, or null when unavailable. */\nexport type B2Sha1Reader = (\n  path: B2SyncPath,\n  signal?: AbortSignal,\n) => Promise<string | null | B2Sha1ReadResult>\n\n/** Options for preparing a file pair before comparison. */\nexport interface PreparePairForCompareOptions {\n  /** Signal used to abort local file hashing. */\n  readonly signal?: AbortSignal\n  /** Optional idle/no-progress timeout for local SHA-1 reads. */\n  readonly sha1ReadTimeoutMillis?: number\n  /** Optional local hashing override for tests or custom runtimes. */\n  readonly readLocalSha1?: LocalSha1Reader\n  /** Optional B2 hashing override used to verify metadata matches before skipping. */\n  readonly readB2Sha1?: B2Sha1Reader\n}\n\n/** Options for preparing multiple file pairs before comparison. */\nexport interface PreparePairsForCompareOptions extends PreparePairForCompareOptions {\n  /** Maximum number of file pairs to prepare concurrently. */\n  readonly concurrency?: number\n}\n\n/** Result of preparing a file pair before policy comparison. */\nexport interface ComparePreparationResult {\n  /** The pair with compare-mode metadata populated where possible. */\n  readonly pair: SyncPair\n  /** Events surfaced while preparing the pair, such as per-file hash errors or skips. */\n  readonly events: readonly SyncEvent[]\n  /** Errors surfaced while preparing the pair. These contribute to the final summary. */\n  readonly errors: readonly Error[]\n  /** Local file bytes read for hashing while preparing this pair. */\n  readonly bytesHashed: number\n  /** B2 bytes read for untrusted metadata verification while preparing this pair. */\n  readonly bytesVerified: number\n  /** Whether action generation should be skipped for this pair. */\n  readonly skipActionGeneration: boolean\n  /** Whether preparation stopped because the abort signal fired. */\n  readonly aborted: boolean\n}\n\n/** A prepared pair result with the original pair retained for event context. */\nexport interface PreparedComparePair {\n  /** Original pair from {@link zipFolders}. */\n  readonly originalPair: SyncPair\n  /** Preparation result for the original pair. */\n  readonly prepared: ComparePreparationResult\n}\n\n/**\n * Determines whether two files should be considered different based on the compare mode.\n * For `sha1`, callers that use the low-level policy helpers should first prepare the pair so\n * local hashes and comparable B2 hashes are populated.\n *\n * @param source - The source file metadata.\n * @param dest - The destination file metadata.\n * @param compareMode - The comparison strategy: 'modtime', 'size', 'sha1', or 'none'.\n * @param threshold - Tolerance for the comparison (bytes for size, milliseconds for modtime).\n *\n * @returns `true` if the files are considered different.\n *\n * @throws When `compareMode` is not one of the supported compare modes.\n */\nexport function filesAreDifferent(\n  source: SyncPath,\n  dest: SyncPath,\n  compareMode: CompareMode,\n  threshold = 0,\n): boolean {\n  switch (compareMode) {\n    case 'none':\n      return false\n    case 'size':\n      return Math.abs(source.size - dest.size) > threshold\n    case 'sha1':\n      return sha1ValuesAreDifferent(source, dest)\n    case 'modtime':\n      return Math.abs(source.modTimeMillis - dest.modTimeMillis) > threshold\n    default:\n      throw new Error(`Unsupported compare mode: ${String(compareMode)}`)\n  }\n}\n\n/**\n * Throws when a runtime compare mode value is unsupported.\n *\n * @param compareMode - User-supplied compare mode.\n *\n * @throws When `compareMode` is not one of the supported values.\n */\nexport function assertSupportedCompareMode(\n  compareMode: unknown,\n): asserts compareMode is CompareMode {\n  switch (compareMode) {\n    case 'none':\n    case 'size':\n    case 'sha1':\n    case 'modtime':\n      return\n    default:\n      throw new Error(`Unsupported compare mode: ${String(compareMode)}`)\n  }\n}\n\nfunction sha1ValuesAreDifferent(source: SyncPath, dest: SyncPath): boolean {\n  if (source.size !== dest.size) return true\n\n  const sourceSha1 = comparableSha1(source)\n  const destSha1 = comparableSha1(dest)\n  if (sourceSha1.kind === 'untrusted' || destSha1.kind === 'untrusted') return true\n  if (sourceSha1.kind === 'unavailable' || destSha1.kind === 'unavailable') return true\n  return sourceSha1.value !== destSha1.value\n}\n\n/**\n * Prepares a pair for the selected compare mode.\n *\n * For `sha1`, this fills missing B2 hashes from comparable metadata and, when an explicit local\n * reader is supplied, hashes the local side only when size cannot already prove a difference.\n * Reader failures are converted into per-file sync events instead of aborting the whole run.\n *\n * @param pair - Source/destination pair from {@link zipFolders}.\n * @param compareMode - The comparison strategy.\n * @param options - Optional hashing dependencies and cancellation signal.\n *\n * @returns The prepared pair plus any preparation events.\n */\nexport async function preparePairForCompare(\n  pair: SyncPair,\n  compareMode: CompareMode,\n  options: PreparePairForCompareOptions = {},\n): Promise<ComparePreparationResult> {\n  assertSupportedCompareMode(compareMode)\n  if (compareMode !== 'sha1') return readyComparePair(pair)\n\n  const [source, dest] = pair\n  if (source === null || dest === null) return readyComparePair(pair)\n  if (source.size !== dest.size) return readyComparePair(pair)\n\n  const metadataPair: SyncPair = [withB2ContentSha1(source), withB2ContentSha1(dest)]\n  if (hasUnavailableB2Sha1(metadataPair)) {\n    return skipped(metadataPair, unavailableSha1Event(metadataPair))\n  }\n  if (\n    options.readB2Sha1 === undefined &&\n    hasUntrustedSha1(metadataPair) &&\n    !hasVerifiableUntrustedSha1(metadataPair)\n  ) {\n    return readyComparePair(metadataPair)\n  }\n\n  const [metadataSource, metadataDest] = metadataPair\n  if (metadataSource === null || metadataDest === null) return readyComparePair(metadataPair)\n\n  const sourceResult = await prepareLocalPathSha1(metadataSource, options)\n  if (sourceResult.aborted) return aborted(metadataPair)\n  if (sourceResult.event) {\n    return skipped(metadataPair, sourceResult.event, sourceResult.error, sourceResult.bytesHashed)\n  }\n\n  const destResult = await prepareLocalPathSha1(metadataDest, options)\n  if (destResult.aborted) return aborted([sourceResult.path, destResult.path])\n  if (destResult.event) {\n    return skipped(\n      [sourceResult.path, destResult.path],\n      destResult.event,\n      destResult.error,\n      sourceResult.bytesHashed,\n    )\n  }\n\n  const preparedPair: SyncPair = [sourceResult.path, destResult.path]\n  const sourceState = comparableSha1(sourceResult.path)\n  const destState = comparableSha1(destResult.path)\n  const bytesHashed = sourceResult.bytesHashed + destResult.bytesHashed\n\n  if (sourceState.kind === 'unavailable' || destState.kind === 'unavailable') {\n    return skipped(preparedPair, unavailableSha1Event(preparedPair), undefined, bytesHashed)\n  }\n\n  const shouldVerifyB2Bytes = untrustedSha1CouldSuppressTransfer(sourceState, destState)\n  const readB2Sha1 = options.readB2Sha1\n  if (shouldVerifyB2Bytes && hasB2Path(preparedPair) && readB2Sha1 !== undefined) {\n    return verifyB2Sha1Bytes(preparedPair, { ...options, readB2Sha1 }, bytesHashed)\n  }\n\n  return readyComparePair(preparedPair, bytesHashed)\n}\n\n/**\n * Prepares a list of pairs for the selected compare mode with bounded concurrency.\n *\n * @param pairs - Source/destination pairs from {@link zipFolders}.\n * @param compareMode - The comparison strategy.\n * @param options - Optional hashing dependencies, cancellation signal, and concurrency.\n *\n * @returns Prepared results in the same order as the input pairs.\n */\nexport async function preparePairsForCompare(\n  pairs: readonly SyncPair[],\n  compareMode: CompareMode,\n  options: PreparePairsForCompareOptions = {},\n): Promise<PreparedComparePair[]> {\n  assertSupportedCompareMode(compareMode)\n  if (compareMode !== 'sha1') {\n    return pairs.map((pair) => ({ originalPair: pair, prepared: readyComparePair(pair) }))\n  }\n\n  const concurrency = normalizeConcurrency(options.concurrency)\n  return mapConcurrent(pairs, concurrency, async (pair): Promise<PreparedComparePair> => {\n    if (options.signal?.aborted) return { originalPair: pair, prepared: aborted(pair) }\n    return {\n      originalPair: pair,\n      prepared: await preparePairForCompare(pair, compareMode, options),\n    }\n  })\n}\n\ntype Sha1State =\n  | { readonly kind: 'verified'; readonly value: string }\n  | { readonly kind: 'untrusted'; readonly value: string | null }\n  | { readonly kind: 'unavailable' }\n\ninterface PreparedPath {\n  readonly path: SyncPath\n  readonly bytesHashed: number\n  readonly bytesVerified: number\n  readonly event?: SyncEvent\n  readonly error?: Error\n  readonly aborted: boolean\n}\n\nasync function prepareLocalPathSha1(\n  path: SyncPath,\n  options: PreparePairForCompareOptions,\n): Promise<PreparedPath> {\n  if (!isLocalSyncPath(path)) {\n    return { path, bytesHashed: 0, bytesVerified: 0, aborted: false }\n  }\n\n  if (options.signal?.aborted) return { path, bytesHashed: 0, bytesVerified: 0, aborted: true }\n\n  try {\n    const state = syncSha1StateOf(path)\n    if (state.kind === 'verified') {\n      return {\n        path: { ...path, contentSha1: state.value },\n        bytesHashed: 0,\n        bytesVerified: 0,\n        aborted: false,\n      }\n    }\n    if (state.kind === 'unavailable') {\n      return {\n        path: { ...path, contentSha1: null },\n        bytesHashed: 0,\n        bytesVerified: 0,\n        aborted: false,\n      }\n    }\n\n    const readLocalSha1 = options.readLocalSha1\n    if (readLocalSha1 === undefined) {\n      return {\n        path: { ...path, contentSha1: path.contentSha1 ?? null },\n        bytesHashed: 0,\n        bytesVerified: 0,\n        aborted: false,\n      }\n    }\n    const contentSha1 = await readLocalSha1(path, options.signal, {\n      ...(options.sha1ReadTimeoutMillis !== undefined\n        ? { timeoutMillis: options.sha1ReadTimeoutMillis }\n        : {}),\n    })\n    return {\n      path: {\n        ...path,\n        contentSha1,\n      },\n      bytesHashed: normalizeVerifiableSha1(contentSha1) === null ? 0 : path.size,\n      bytesVerified: 0,\n      aborted: false,\n    }\n  } catch (err) {\n    if (isSignalAbortError(options.signal, err)) {\n      return { path, bytesHashed: 0, bytesVerified: 0, aborted: true }\n    }\n    const error = toError(err)\n    return {\n      path,\n      bytesHashed: 0,\n      event: {\n        type: 'error',\n        path: path.relativePath,\n        size: 0,\n        message: `failed to hash local file for sha1 comparison: ${formatHashError(error)}`,\n      },\n      error,\n      bytesVerified: 0,\n      aborted: false,\n    }\n  }\n}\n\nasync function verifyB2Sha1Bytes(\n  pair: SyncPair,\n  options: PreparePairForCompareOptions & { readonly readB2Sha1: B2Sha1Reader },\n  bytesHashed: number,\n): Promise<ComparePreparationResult> {\n  const [source, dest] = pair\n  /* v8 ignore next -- callers only verify B2 bytes for paired compare results */\n  if (source === null || dest === null) return readyComparePair(pair, bytesHashed)\n\n  const sourceResult = await prepareUntrustedB2PathSha1(source, options)\n  const sourceBytesVerified = sourceResult.bytesVerified\n  if (sourceResult.aborted) return aborted(pair)\n  if (sourceResult.event) {\n    return skipped(\n      [sourceResult.path, dest],\n      sourceResult.event,\n      sourceResult.error,\n      bytesHashed,\n      sourceBytesVerified,\n    )\n  }\n\n  const destResult = await prepareUntrustedB2PathSha1(dest, options)\n  const bytesVerified = sourceBytesVerified + destResult.bytesVerified\n  /* v8 ignore next -- destination abort mirrors the covered source abort path */\n  if (destResult.aborted) return aborted([sourceResult.path, destResult.path])\n  if (destResult.event) {\n    return skipped(\n      [sourceResult.path, destResult.path],\n      destResult.event,\n      destResult.error,\n      bytesHashed,\n      bytesVerified,\n    )\n  }\n\n  return readyComparePair([sourceResult.path, destResult.path], bytesHashed, bytesVerified)\n}\n\nasync function prepareUntrustedB2PathSha1(\n  path: SyncPath,\n  options: PreparePairForCompareOptions & { readonly readB2Sha1: B2Sha1Reader },\n): Promise<PreparedPath> {\n  if (!isB2SyncPath(path) || comparableSha1(path).kind !== 'untrusted') {\n    return { path, bytesHashed: 0, bytesVerified: 0, aborted: false }\n  }\n  return prepareB2PathSha1(path, options)\n}\n\nasync function prepareB2PathSha1(\n  path: B2SyncPath,\n  options: PreparePairForCompareOptions & { readonly readB2Sha1: B2Sha1Reader },\n): Promise<PreparedPath> {\n  /* v8 ignore next -- pre-aborted B2 reads are covered at pair level */\n  if (options.signal?.aborted) return { path, bytesHashed: 0, bytesVerified: 0, aborted: true }\n\n  try {\n    const result = await options.readB2Sha1(path, options.signal)\n    const contentSha1 = typeof result === 'object' && result !== null ? result.contentSha1 : result\n    const bytesVerified =\n      typeof result === 'object' && result !== null ? Math.max(0, result.bytesRead) : 0\n    const preparedPath = {\n      ...path,\n      contentSha1,\n      contentSha1State: syncSha1StateOf({ contentSha1 }),\n    }\n    if (contentSha1 === null) {\n      return {\n        path: preparedPath,\n        bytesHashed: 0,\n        bytesVerified,\n        event: unavailableSha1PathEvent(path),\n        aborted: false,\n      }\n    }\n    return {\n      path: preparedPath,\n      bytesHashed: 0,\n      bytesVerified,\n      aborted: false,\n    }\n  } catch (err) {\n    if (isSignalAbortError(options.signal, err)) {\n      return { path, bytesHashed: 0, bytesVerified: 0, aborted: true }\n    }\n    const error = toError(err)\n    return {\n      path,\n      bytesHashed: 0,\n      bytesVerified: 0,\n      event: {\n        type: 'skip',\n        path: path.relativePath,\n        size: 0,\n        message: `sha1 comparison skipped because B2 verification failed: ${formatHashError(error)}`,\n      },\n      aborted: false,\n    }\n  }\n}\n\nfunction comparableSha1(path: SyncPath): Sha1State {\n  const state = syncSha1StateOf(path)\n  if (state.kind === 'verified') return { kind: 'verified', value: state.value }\n  if (state.kind === 'untrusted') return { kind: 'untrusted', value: state.value }\n  return { kind: 'unavailable' }\n}\n\nfunction untrustedSha1CouldSuppressTransfer(source: Sha1State, dest: Sha1State): boolean {\n  if (source.kind === 'untrusted' && dest.kind === 'verified') return source.value === dest.value\n  if (dest.kind === 'untrusted' && source.kind === 'verified') return dest.value === source.value\n  if (source.kind === 'untrusted' && dest.kind === 'untrusted') {\n    return source.value !== null && source.value === dest.value\n  }\n  return false\n}\n\nfunction withB2ContentSha1(path: SyncPath): SyncPath {\n  if (\n    !isB2SyncPath(path) ||\n    path.contentSha1 !== undefined ||\n    path.contentSha1State !== undefined\n  ) {\n    return path\n  }\n  const contentSha1 = selectB2ComparableSha1(path.selectedVersion)\n  return { ...path, contentSha1, contentSha1State: syncSha1StateOf({ contentSha1 }) }\n}\n\nfunction hasUnavailableB2Sha1(pair: SyncPair): boolean {\n  const [source, dest] = pair\n  return (\n    (source !== null && isB2SyncPath(source) && comparableSha1(source).kind === 'unavailable') ||\n    (dest !== null && isB2SyncPath(dest) && comparableSha1(dest).kind === 'unavailable')\n  )\n}\n\nfunction hasUntrustedSha1(pair: SyncPair): boolean {\n  const [source, dest] = pair\n  return (\n    (source !== null && comparableSha1(source).kind === 'untrusted') ||\n    (dest !== null && comparableSha1(dest).kind === 'untrusted')\n  )\n}\n\nfunction hasVerifiableUntrustedSha1(pair: SyncPair): boolean {\n  const [source, dest] = pair\n  return (\n    (source !== null && verifiableUntrustedSha1(source)) ||\n    (dest !== null && verifiableUntrustedSha1(dest))\n  )\n}\n\nfunction verifiableUntrustedSha1(path: SyncPath): boolean {\n  const state = comparableSha1(path)\n  return state.kind === 'untrusted' && state.value !== null\n}\n\nfunction hasB2Path(pair: SyncPair): boolean {\n  const [source, dest] = pair\n  return (source !== null && isB2SyncPath(source)) || (dest !== null && isB2SyncPath(dest))\n}\n\nfunction isB2SyncPath(path: SyncPath): path is B2SyncPath {\n  return 'selectedVersion' in path\n}\n\nfunction isLocalSyncPath(path: SyncPath): path is LocalSyncPath {\n  return 'absolutePath' in path\n}\n\n/**\n * Creates a successful no-op compare preparation result for a pair.\n *\n * @param pair - Source/destination pair from {@link zipFolders}.\n * @param bytesHashed - Local file bytes read while preparing the pair.\n * @param bytesVerified - B2 bytes read while verifying untrusted SHA-1 metadata.\n *\n * @returns A ready preparation result that allows action generation.\n */\nexport function readyComparePair(\n  pair: SyncPair,\n  bytesHashed = 0,\n  bytesVerified = 0,\n): ComparePreparationResult {\n  return {\n    pair,\n    events: [],\n    errors: [],\n    bytesHashed,\n    bytesVerified,\n    skipActionGeneration: false,\n    aborted: false,\n  }\n}\n\nfunction skipped(\n  pair: SyncPair,\n  event: SyncEvent,\n  error?: Error,\n  bytesHashed = 0,\n  bytesVerified = 0,\n): ComparePreparationResult {\n  return {\n    pair,\n    events: [event],\n    errors: error !== undefined ? [error] : [],\n    bytesHashed,\n    bytesVerified,\n    skipActionGeneration: true,\n    aborted: false,\n  }\n}\n\nfunction aborted(pair: SyncPair): ComparePreparationResult {\n  return {\n    pair,\n    events: [],\n    errors: [],\n    bytesHashed: 0,\n    bytesVerified: 0,\n    skipActionGeneration: true,\n    aborted: true,\n  }\n}\n\nfunction unavailableSha1Event(pair: SyncPair): SyncSkipEvent {\n  /* v8 ignore next -- unavailable SHA-1 events always have at least one side */\n  const path = (pair[0] ?? pair[1])?.relativePath ?? ''\n  return unavailableSha1PathEvent({ relativePath: path })\n}\n\nfunction unavailableSha1PathEvent(path: Pick<SyncPath, 'relativePath'>): SyncSkipEvent {\n  return {\n    type: 'skip',\n    path: path.relativePath,\n    size: 0,\n    message: 'sha1 comparison skipped because a verifiable SHA-1 is unavailable',\n  }\n}\n\nfunction normalizeConcurrency(value: number | undefined): number {\n  if (value === undefined || !Number.isFinite(value) || value < 1) return 1\n  return Math.max(1, Math.floor(value))\n}\n"],"mappings":"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"}

package/dist/sync/policies/compare.d.cts

@@ -1,13 +1,111 @@
-import { CompareMode, SyncPath } from '../types.js';
+import { LocalSha1Reader } from '../local-sha1.js';
+import { SyncPair } from '../pairing.js';
+import { B2SyncPath, CompareMode, SyncEvent, SyncPath } from '../types.js';
+export { selectB2ComparableSha1 } from '../sha1-metadata.js';
+/** Result from a B2 SHA-1 verification read. */
+export interface B2Sha1ReadResult {
+    /** SHA-1 digest of the selected B2 bytes, or null when unavailable. */
+    readonly contentSha1: string | null;
+    /** Number of B2 bytes downloaded and hashed while verifying. */
+    readonly bytesRead: number;
+}
+/** Reads a B2 file and returns the SHA-1 digest of its actual bytes, or null when unavailable. */
+export type B2Sha1Reader = (path: B2SyncPath, signal?: AbortSignal) => Promise<string | null | B2Sha1ReadResult>;
+/** Options for preparing a file pair before comparison. */
+export interface PreparePairForCompareOptions {
+    /** Signal used to abort local file hashing. */
+    readonly signal?: AbortSignal;
+    /** Optional idle/no-progress timeout for local SHA-1 reads. */
+    readonly sha1ReadTimeoutMillis?: number;
+    /** Optional local hashing override for tests or custom runtimes. */
+    readonly readLocalSha1?: LocalSha1Reader;
+    /** Optional B2 hashing override used to verify metadata matches before skipping. */
+    readonly readB2Sha1?: B2Sha1Reader;
+}
+/** Options for preparing multiple file pairs before comparison. */
+export interface PreparePairsForCompareOptions extends PreparePairForCompareOptions {
+    /** Maximum number of file pairs to prepare concurrently. */
+    readonly concurrency?: number;
+}
+/** Result of preparing a file pair before policy comparison. */
+export interface ComparePreparationResult {
+    /** The pair with compare-mode metadata populated where possible. */
+    readonly pair: SyncPair;
+    /** Events surfaced while preparing the pair, such as per-file hash errors or skips. */
+    readonly events: readonly SyncEvent[];
+    /** Errors surfaced while preparing the pair. These contribute to the final summary. */
+    readonly errors: readonly Error[];
+    /** Local file bytes read for hashing while preparing this pair. */
+    readonly bytesHashed: number;
+    /** B2 bytes read for untrusted metadata verification while preparing this pair. */
+    readonly bytesVerified: number;
+    /** Whether action generation should be skipped for this pair. */
+    readonly skipActionGeneration: boolean;
+    /** Whether preparation stopped because the abort signal fired. */
+    readonly aborted: boolean;
+}
+/** A prepared pair result with the original pair retained for event context. */
+export interface PreparedComparePair {
+    /** Original pair from {@link zipFolders}. */
+    readonly originalPair: SyncPair;
+    /** Preparation result for the original pair. */
+    readonly prepared: ComparePreparationResult;
+}
 /**
  * Determines whether two files should be considered different based on the compare mode.
+ * For `sha1`, callers that use the low-level policy helpers should first prepare the pair so
+ * local hashes and comparable B2 hashes are populated.
  *
  * @param source - The source file metadata.
  * @param dest - The destination file metadata.
- * @param compareMode - The comparison strategy: 'modtime', 'size', or 'none'.
+ * @param compareMode - The comparison strategy: 'modtime', 'size', 'sha1', or 'none'.
  * @param threshold - Tolerance for the comparison (bytes for size, milliseconds for modtime).
  *
  * @returns `true` if the files are considered different.
+ *
+ * @throws When `compareMode` is not one of the supported compare modes.
  */
 export declare function filesAreDifferent(source: SyncPath, dest: SyncPath, compareMode: CompareMode, threshold?: number): boolean;
+/**
+ * Throws when a runtime compare mode value is unsupported.
+ *
+ * @param compareMode - User-supplied compare mode.
+ *
+ * @throws When `compareMode` is not one of the supported values.
+ */
+export declare function assertSupportedCompareMode(compareMode: unknown): asserts compareMode is CompareMode;
+/**
+ * Prepares a pair for the selected compare mode.
+ *
+ * For `sha1`, this fills missing B2 hashes from comparable metadata and, when an explicit local
+ * reader is supplied, hashes the local side only when size cannot already prove a difference.
+ * Reader failures are converted into per-file sync events instead of aborting the whole run.
+ *
+ * @param pair - Source/destination pair from {@link zipFolders}.
+ * @param compareMode - The comparison strategy.
+ * @param options - Optional hashing dependencies and cancellation signal.
+ *
+ * @returns The prepared pair plus any preparation events.
+ */
+export declare function preparePairForCompare(pair: SyncPair, compareMode: CompareMode, options?: PreparePairForCompareOptions): Promise<ComparePreparationResult>;
+/**
+ * Prepares a list of pairs for the selected compare mode with bounded concurrency.
+ *
+ * @param pairs - Source/destination pairs from {@link zipFolders}.
+ * @param compareMode - The comparison strategy.
+ * @param options - Optional hashing dependencies, cancellation signal, and concurrency.
+ *
+ * @returns Prepared results in the same order as the input pairs.
+ */
+export declare function preparePairsForCompare(pairs: readonly SyncPair[], compareMode: CompareMode, options?: PreparePairsForCompareOptions): Promise<PreparedComparePair[]>;
+/**
+ * Creates a successful no-op compare preparation result for a pair.
+ *
+ * @param pair - Source/destination pair from {@link zipFolders}.
+ * @param bytesHashed - Local file bytes read while preparing the pair.
+ * @param bytesVerified - B2 bytes read while verifying untrusted SHA-1 metadata.
+ *
+ * @returns A ready preparation result that allows action generation.
+ */
+export declare function readyComparePair(pair: SyncPair, bytesHashed?: number, bytesVerified?: number): ComparePreparationResult;
 //# sourceMappingURL=compare.d.ts.map

package/dist/sync/policies/compare.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../../src/sync/policies/compare.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAExD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,QAAQ,EAChB,IAAI,EAAE,QAAQ,EACd,WAAW,EAAE,WAAW,EACxB,SAAS,SAAI,GACZ,OAAO,CAST"}
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../../src/sync/policies/compare.js"],"names":[],"mappings":"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"}