@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/sync/synchronizer.js

@@ -1,181 +1,787 @@
-import { BufferSource } from "../streams/source.js";
 import { fileId } from "../types/ids.js";
-import { Semaphore } from "../upload/concurrency.js";
-import { DEFAULT_TRANSFER_CONCURRENCY } from "../util/defaults.js";
-import { toError } from "../util/to-error.js";
-import { DeleteLocalAction, DeleteRemoteAction, HideAction, CopyAction, DownloadAction, UploadAction } from "./actions/index.js";
+import { FileSource } from "../streams/file-source.js";
+import { CopyAction, DeleteLocalAction, DeleteRemoteAction, DownloadAction, HideAction, SkipAction, UploadAction } from "./actions/index.js";
 import { zipFolders } from "./pairing.js";
+import { sanitizeErrorReason } from "../util/error-reason.js";
+import { DEFAULT_SHA1_VERIFICATION_TIMEOUT_MILLIS, normalizeSha1TimeoutMillis } from "./sha1-options.js";
+import { readLocalSha1File } from "./local-sha1.js";
+import { assertSupportedCompareMode, preparePairsForCompare, readyComparePair } from "./policies/compare.js";
 import { generateActions } from "./policies/index.js";
+import { safeRelativePathSegments } from "./path-safety.js";
+import { asRawB2KeyPrefix, b2KeyToRelativePathUnderPrefix } from "./prefix.js";
+import { localFilesystemErrorReason } from "./filesystem-errors.js";
+import { isLocalFilesystemRoot } from "./local-filesystem-root.js";
+import { hashReadableStreamSha1, normalizeSha1VerificationMaxBytes, withSha1VerificationDeadline } from "./b2-sha1-reader.js";
+import { deleteLocalFileInsideRoot, validateScannedLocalFile, writeLocalStreamInsideRoot } from "./local-file-io.js";
+//#region src/sync/synchronizer.ts
+var MAX_BUFFERED_SCAN_EVENTS = 100;
+var MAX_AGGREGATE_FAILED_PATHS = 100;
+var DEFAULT_DOWNLOAD_IDLE_TIMEOUT_MILLIS = 6e4;
+/**
+* Test hooks for bounded planning behavior.
+*
+* @internal
+*/
+var synchronizerTestHooks = {};
+/**
+* Infers the sync direction from the source and destination folder types.
+* @param source - The folder to read files from.
+* @param dest - The folder to write files to.
+*
+* @returns The resolved sync direction based on folder types.
+*
+* @throws When the source and destination folder types form an unsupported combination.
+*/
 function resolveDirection(source, dest) {
-  if (source.type === "local" && dest.type === "b2") return "local-to-b2";
-  if (source.type === "b2" && dest.type === "local") return "b2-to-local";
-  if (source.type === "b2" && dest.type === "b2") return "b2-to-b2";
-  throw new Error(`Unsupported sync direction: ${source.type} to ${dest.type}`);
+	if (source.type === "local" && dest.type === "b2") return "local-to-b2";
+	if (source.type === "b2" && dest.type === "local") return "b2-to-local";
+	if (source.type === "b2" && dest.type === "b2") return "b2-to-b2";
+	throw new Error(`Unsupported sync direction: ${source.type} to ${dest.type}`);
 }
 async function* synchronize(config) {
-  const { source, dest, options } = config;
-  const direction = resolveDirection(source, dest);
-  const dryRun = options.dryRun ?? false;
-  const concurrency = options.concurrency ?? DEFAULT_TRANSFER_CONCURRENCY;
-  const keepDays = options.keepDays ?? 0;
-  const compareThreshold = options.compareThreshold ?? 0;
-  const nowMillis = Date.now();
-  const factory = createActionFactory(config);
-  const actions = [];
-  for await (const pair of zipFolders(source, dest)) {
-    if (options.signal?.aborted) return;
-    for (const action of generateActions(
-      pair,
-      direction,
-      options.compareMode,
-      options.keepMode,
-      keepDays,
-      nowMillis,
-      factory,
-      compareThreshold
-    )) {
-      actions.push(action);
-    }
-    yield { type: "compare", path: (pair[0] ?? pair[1])?.relativePath ?? "", size: 0 };
-  }
-  const sem = new Semaphore(concurrency);
-  const results = [];
-  const errors = [];
-  const promises = actions.map(async (action) => {
-    await sem.acquire();
-    try {
-      if (options.signal?.aborted) return;
-      const event = await action.execute(dryRun);
-      results.push(event);
-    } catch (err) {
-      const errorValue = toError(err);
-      errors.push(errorValue);
-      results.push({
-        type: "error",
-        path: action.relativePath,
-        size: 0,
-        message: errorValue.message
-      });
-    } finally {
-      sem.release();
-    }
-  });
-  await Promise.all(promises);
-  for (const event of results) {
-    yield event;
-  }
-  if (errors.length > 0) {
-    yield {
-      type: "error",
-      path: "",
-      size: 0,
-      message: `${errors.length} action(s) failed`
-    };
-  }
+	const { source, dest, options } = config;
+	assertSupportedCompareMode(options.compareMode);
+	const direction = resolveDirection(source, dest);
+	const dryRun = options.dryRun ?? false;
+	const concurrency = normalizeSyncConcurrency(options.concurrency);
+	const keepDays = options.keepDays ?? 0;
+	const compareThreshold = options.compareThreshold ?? 0;
+	const nowMillis = Date.now();
+	const localRootContexts = await resolveLocalRootContexts(config);
+	const queuedEvents = [];
+	const failedPaths = [];
+	const failedPathSet = /* @__PURE__ */ new Set();
+	let errorCount = 0;
+	let failedPathOmittedCount = 0;
+	let scanHadError = false;
+	const runningActions = /* @__PURE__ */ new Set();
+	const scanEvents = {
+		events: [],
+		dropped: 0
+	};
+	const scanOptions = {
+		...options.include !== void 0 ? { include: options.include } : {},
+		...options.exclude !== void 0 ? { exclude: options.exclude } : {},
+		...options.signal !== void 0 ? { signal: options.signal } : {},
+		...options.maxScanEntries !== void 0 ? { maxScanEntries: options.maxScanEntries } : {},
+		...direction === "b2-to-local" ? { requireLocalSafePaths: true } : {},
+		onError: (event) => {
+			scanHadError = true;
+			recordSyncError(event);
+			queueEvent(event);
+		}
+	};
+	const factory = createActionFactory(config, localRootContexts);
+	const readB2Sha1 = dryRun ? void 0 : createB2Sha1Reader(config);
+	const actionAbortController = new AbortController();
+	const removeAbortForwarder = forwardAbortSignal(options.signal, actionAbortController);
+	let completed = false;
+	async function* finishAfterAbort() {
+		await drainActions();
+		yield* emitQueuedEvents();
+	}
+	try {
+		let pairs;
+		try {
+			pairs = await collectPairs();
+		} catch (err) {
+			await drainActions();
+			if (options.signal?.aborted) {
+				yield* finishAfterAbort();
+				return;
+			}
+			if (!scanHadError) {
+				yield* emitQueuedEvents();
+				throw err;
+			}
+			yield* emitQueuedEvents();
+			yield aggregateErrorEvent();
+			completed = true;
+			return;
+		}
+		yield* emitQueuedEvents();
+		const filesystemError = scanFilesystemError(scanEvents);
+		if (filesystemError !== void 0) throw filesystemError;
+		if (options.signal?.aborted) {
+			yield* finishAfterAbort();
+			return;
+		}
+		if (scanHadError) {
+			if (errorCount > 0) yield aggregateErrorEvent();
+			completed = true;
+			return;
+		}
+		if (options.compareMode === "sha1") {
+			const compareBatchSize = concurrency;
+			for (let index = 0; index < pairs.length; index += compareBatchSize) if (yield* emitSha1Batch(pairs.slice(index, index + compareBatchSize))) return;
+		} else for (let index = 0; index < pairs.length; index += concurrency) {
+			const items = pairs.slice(index, index + concurrency).map((pair) => planPreparedPair(pair, readyComparePair(pair)));
+			synchronizerTestHooks.afterNonSha1PlanBatch?.(items.length);
+			if (yield* emitPreparedItems(items)) return;
+		}
+		await drainActions();
+		yield* emitQueuedEvents();
+		if (errorCount > 0) yield aggregateErrorEvent();
+		completed = true;
+	} finally {
+		if (!completed) abortActionController(actionAbortController, new DOMException("Sync iterator closed", "AbortError"));
+		removeAbortForwarder();
+		await drainActions();
+	}
+	async function collectPairs() {
+		const pairs = [];
+		for await (const pair of zipFolders(source, dest, scanOptions, {
+			onSourceSkip(event) {
+				bufferScanEvent(scanEvents, event, direction, "source");
+			},
+			onDestSkip(event) {
+				bufferScanEvent(scanEvents, event, direction, "dest");
+			}
+		})) {
+			if (options.signal?.aborted) return pairs;
+			validateB2SourcePairPrefix(pair, config);
+			pairs.push(pair);
+		}
+		return pairs;
+	}
+	async function* emitSha1Batch(batch) {
+		if (batch.length === 0) return false;
+		await drainActions();
+		yield* emitQueuedEvents();
+		const preparedBatch = await processPreparedBatch(batch);
+		if (yield* emitPreparedItems(preparedBatch.items)) return true;
+		if (preparedBatch.aborted || options.signal?.aborted) {
+			yield* finishAfterAbort();
+			return true;
+		}
+		return false;
+	}
+	async function* emitPreparedItems(items) {
+		for (const item of items) {
+			yield* emitQueuedEvents();
+			yield item.event;
+			yield* emitQueuedEvents();
+			/* v8 ignore next -- abort between compare yield and scheduling is timing-dependent */
+			if (options.signal?.aborted) {
+				yield* finishAfterAbort();
+				return true;
+			}
+			for (const action of item.actions) {
+				await scheduleAction(action);
+				yield* emitQueuedEvents();
+			}
+		}
+		return false;
+	}
+	async function processPreparedBatch(batch) {
+		if (batch.length === 0) return {
+			items: [],
+			aborted: false
+		};
+		const preparedPairs = await preparePairsForCompare(batch, "sha1", {
+			concurrency,
+			...options.signal !== void 0 ? { signal: options.signal } : {},
+			...options.sha1ReadTimeoutMillis !== void 0 ? { sha1ReadTimeoutMillis: options.sha1ReadTimeoutMillis } : {},
+			readLocalSha1: readLocalSha1File,
+			...readB2Sha1 !== void 0 ? { readB2Sha1 } : {}
+		});
+		const items = [];
+		for (const { originalPair, prepared } of preparedPairs) {
+			if (prepared.aborted || options.signal?.aborted) return {
+				items,
+				aborted: true
+			};
+			items.push(planPreparedPair(originalPair, prepared));
+		}
+		return {
+			items,
+			aborted: false
+		};
+	}
+	function planPreparedPair(pair, prepared) {
+		const event = {
+			type: "compare",
+			path: (pair[0] ?? pair[1])?.relativePath ?? "",
+			size: 0,
+			bytesHashed: prepared.bytesHashed,
+			...prepared.bytesVerified > 0 ? { bytesVerified: prepared.bytesVerified } : {}
+		};
+		let preparedErrorEventCount = 0;
+		for (const preparedEvent of prepared.events) {
+			queueEvent(preparedEvent);
+			if (preparedEvent.type === "error") {
+				preparedErrorEventCount++;
+				recordFailurePath(preparedEvent.path);
+			}
+		}
+		errorCount += prepared.errors.length;
+		for (let index = preparedErrorEventCount; index < prepared.errors.length; index++) recordFailurePath(event.path);
+		if (prepared.skipActionGeneration) return {
+			event,
+			actions: []
+		};
+		if ((scanHadError || scanHadFilesystemError(scanEvents)) && prepared.pair[0] === null && prepared.pair[1] !== null) return {
+			event,
+			actions: [new SkipAction(prepared.pair[1].relativePath, "not removed because scan errors occurred")]
+		};
+		if (sourceInventoryIncomplete(scanEvents) && prepared.pair[0] === null && prepared.pair[1] !== null) return {
+			event,
+			actions: [new SkipAction(prepared.pair[1].relativePath, scanEvents.sourceInventoryIncompleteMessage ?? "not removed because the source scan skipped unsafe B2 names")]
+		};
+		return {
+			event,
+			actions: [...generateActions(prepared.pair, direction, options.compareMode, options.keepMode, keepDays, nowMillis, factory, compareThreshold)]
+		};
+	}
+	async function scheduleAction(action) {
+		const task = executeAction(action).finally(() => {
+			runningActions.delete(task);
+		});
+		runningActions.add(task);
+		if (runningActions.size >= concurrency) await Promise.race(runningActions);
+	}
+	async function executeAction(action) {
+		try {
+			if (actionAbortController.signal.aborted) return;
+			queueEvent(await action.execute(dryRun, actionAbortController.signal));
+		} catch (err) {
+			const event = {
+				type: "error",
+				path: action.relativePath,
+				size: 0,
+				message: sanitizeErrorReason(err)
+			};
+			recordSyncError(event);
+			queueEvent(event);
+		}
+	}
+	function recordSyncError(event) {
+		errorCount += 1;
+		recordFailurePath(event.path);
+	}
+	function recordFailurePath(path) {
+		if (path === "") return;
+		if (failedPathSet.has(path)) return;
+		failedPathSet.add(path);
+		if (failedPaths.length < MAX_AGGREGATE_FAILED_PATHS) failedPaths.push(path);
+		else failedPathOmittedCount++;
+	}
+	function aggregateErrorEvent() {
+		return {
+			type: "error",
+			path: "",
+			size: 0,
+			message: `${errorCount} sync error(s) occurred`,
+			failureCount: errorCount,
+			failedPaths: [...failedPaths],
+			...failedPathOmittedCount > 0 ? { failedPathOmittedCount } : {}
+		};
+	}
+	function queueEvent(event) {
+		queuedEvents.push(event);
+	}
+	async function* emitQueuedEvents() {
+		yield* drainScanEvents(scanEvents);
+		for (const event of queuedEvents.splice(0)) yield event;
+	}
+	async function drainActions() {
+		while (runningActions.size > 0) await Promise.race(runningActions);
+	}
 }
+/**
+* Normalizes user-provided sync concurrency before it controls compare batches and transfers.
+*
+* @param value - Optional concurrency value from sync options.
+*
+* @returns A positive integer concurrency value.
+*
+* @throws When the configured concurrency is not a positive integer.
+*/
+function normalizeSyncConcurrency(value) {
+	const candidate = value ?? 4;
+	if (!Number.isInteger(candidate) || candidate < 1) throw new RangeError("Sync concurrency must be a positive integer");
+	return candidate;
+}
+function normalizeDownloadIdleTimeoutMillis(value) {
+	if (value === void 0) return DEFAULT_DOWNLOAD_IDLE_TIMEOUT_MILLIS;
+	if (value === Number.POSITIVE_INFINITY) return value;
+	if (!Number.isFinite(value) || value < 1) throw new RangeError("downloadIdleTimeoutMillis must be a positive finite number or Infinity");
+	return Math.floor(value);
+}
+function assertValidB2ContentLength(contentLength) {
+	if (!Number.isSafeInteger(contentLength) || contentLength < 0) throw new Error("B2 contentLength must be a non-negative safe integer");
+	return contentLength;
+}
+function createB2Sha1Reader(config) {
+	const upConfig = config;
+	const downConfig = config;
+	const bucket = upConfig.bucket ?? downConfig.bucket;
+	if (bucket === void 0) return void 0;
+	const readablePrefixes = b2ReadableRawPrefixes(config);
+	const idleTimeoutMillis = normalizeSha1TimeoutMillis(config.options.sha1ReadTimeoutMillis);
+	const verificationTimeoutMillis = normalizeSha1TimeoutMillis(config.options.sha1VerificationTimeoutMillis, DEFAULT_SHA1_VERIFICATION_TIMEOUT_MILLIS);
+	return async (path, signal) => {
+		const expectedBytes = assertValidB2ContentLength(path.selectedVersion.contentLength);
+		const maxBytes = normalizeSha1VerificationMaxBytes(expectedBytes, config.options.sha1VerificationMaxBytes);
+		return withSha1VerificationDeadline(signal, verificationTimeoutMillis, async (deadlineSignal) => {
+			deadlineSignal.throwIfAborted();
+			if (maxBytes < expectedBytes) throw new Error(`sha1 B2 verification skipped because contentLength ${expectedBytes} exceeds ${maxBytes} byte verification budget`);
+			const serverSideEncryption = toSseCDownloadKey(config.options.encryptionProvider?.getSettingForDownload(path.selectedVersion));
+			const fileName = validateB2SyncPathInAnyPrefix(readablePrefixes, path, "read");
+			const verified = await hashReadableStreamSha1((await bucket.file(fileName).downloadById(path.selectedVersion.fileId, {
+				...serverSideEncryption !== void 0 ? { serverSideEncryption } : {},
+				signal: deadlineSignal
+			})).body, deadlineSignal, {
+				idleTimeoutMillis,
+				maxBytes,
+				expectedBytes
+			});
+			return {
+				contentSha1: verified.contentSha1,
+				bytesRead: verified.bytesRead
+			};
+		});
+	};
+}
+function forwardAbortSignal(source, controller) {
+	if (source === void 0) return () => void 0;
+	if (source.aborted) {
+		abortActionController(controller, source.reason);
+		return () => void 0;
+	}
+	const abort = () => abortActionController(controller, source.reason);
+	source.addEventListener("abort", abort, { once: true });
+	return () => source.removeEventListener("abort", abort);
+}
+function abortActionController(controller, reason) {
+	if (!controller.signal.aborted) controller.abort(reason);
+}
+/**
+* Narrowing assertion that a `Bucket` is present for an action that requires
+* it. Throws with a consistent, context-tagged message when the configured
+* direction did not supply one (e.g. `b2-to-local` direction asking for an
+* upload action).
+*
+* Uses TypeScript's `asserts` signature so call-site flow narrows
+* `bucket` from `Bucket | undefined` to `Bucket` after the check, without
+* requiring a separate `if (!bucket) throw ...` line per action factory.
+*
+* @param bucket - The (possibly missing) bucket reference.
+* @param context - Short verb describing the action being constructed
+*   (e.g. `'upload'`, `'download'`). Surfaced in the error message.
+*
+* @throws `Error` when `bucket` is `undefined` or `null`.
+*/
 function assertBucket(bucket, context) {
-  if (!bucket) throw new Error(`Bucket required for ${context} actions`);
-}
-function createActionFactory(config) {
-  const upConfig = config;
-  const downConfig = config;
-  const destBucket = upConfig.bucket ?? downConfig.bucket;
-  const bucketIsLocked = destBucket?.info?.fileLockConfiguration?.value?.isFileLockEnabled ?? false;
-  const factory = {
-    upload(source) {
-      const bucket = upConfig.bucket;
-      const prefix = upConfig.prefix ?? "";
-      assertBucket(bucket, "upload");
-      return new UploadAction(
-        source.relativePath,
-        source.absolutePath,
-        source.size,
-        async (absPath, relPath) => {
-          const { readFile } = await import("node:fs/promises");
-          const data = await readFile(absPath);
-          await bucket.upload({
-            fileName: `${prefix}${relPath}`,
-            source: new BufferSource(new Uint8Array(data))
-          });
-        }
-      );
-    },
-    download(source) {
-      const bucket = downConfig.bucket;
-      const root = downConfig.dest?.type === "local" ? downConfig.dest.root : "";
-      assertBucket(bucket, "download");
-      return new DownloadAction(source.relativePath, source.size, async (relPath) => {
-        const result = await bucket.download(source.selectedVersion.fileName);
-        const reader = result.body.getReader();
-        let combined;
-        try {
-          const chunks = [];
-          while (true) {
-            const { done, value } = await reader.read();
-            if (done) break;
-            chunks.push(value);
-          }
-          let total = 0;
-          for (const c of chunks) total += c.byteLength;
-          combined = new Uint8Array(total);
-          let offset = 0;
-          for (const c of chunks) {
-            combined.set(c, offset);
-            offset += c.byteLength;
-          }
-        } finally {
-          reader.releaseLock();
-        }
-        const { mkdir, writeFile } = await import("node:fs/promises");
-        const { dirname, join } = await import("node:path");
-        const destPath = join(root, relPath);
-        await mkdir(dirname(destPath), { recursive: true });
-        await writeFile(destPath, combined);
-      });
-    },
-    copy(source, destPath) {
-      const bucket = upConfig.bucket;
-      assertBucket(bucket, "copy");
-      return new CopyAction(source.relativePath, source.size, async () => {
-        await bucket.copyFile({
-          sourceFileId: source.selectedVersion.fileId,
-          fileName: destPath
-        });
-      });
-    },
-    hide(path) {
-      const bucket = upConfig.bucket ?? downConfig.bucket;
-      assertBucket(bucket, "hide");
-      return new HideAction(path, async (relPath) => {
-        const prefix = upConfig.prefix ?? "";
-        await bucket.hideFile(`${prefix}${relPath}`);
-      });
-    },
-    deleteRemote(path) {
-      const bucket = upConfig.bucket ?? downConfig.bucket;
-      assertBucket(bucket, "delete");
-      const b2FileName = path.selectedVersion.fileName;
-      return new DeleteRemoteAction(
-        path.relativePath,
-        path.selectedVersion.fileId,
-        async (fileId$1) => {
-          await bucket.deleteFileVersion(b2FileName, fileId(fileId$1));
-        }
-      );
-    },
-    deleteLocal(path) {
-      return new DeleteLocalAction(path.relativePath, path.absolutePath, async (absPath) => {
-        const { unlink } = await import("node:fs/promises");
-        await unlink(absPath);
-      });
-    },
-    removeOrphan(dest) {
-      return bucketIsLocked ? factory.hide(dest.relativePath) : factory.deleteRemote(dest);
-    }
-  };
-  return factory;
-}
-export {
-  synchronize
-};
-//# sourceMappingURL=synchronizer.js.map
+	if (!bucket) throw new Error(`Bucket required for ${context} actions`);
+}
+/**
+* Returns the root for a local sync folder required by an action.
+*
+* @param folder - The configured folder to validate.
+* @param role - Whether the local folder is the source or destination.
+* @param context - Short verb describing the action being constructed.
+*
+* @returns The local filesystem root.
+*
+* @throws `Error` when the folder is not local or has no root.
+*/
+function requireLocalRoot(folder, role, context) {
+	const root = folder?.type === "local" ? folder.root : void 0;
+	if (typeof root !== "string" || root === "") throw new Error(`Local ${role} root required for ${context} actions`);
+	return root;
+}
+async function resolveLocalRootContexts(config) {
+	const sourceIsLocalFilesystem = isLocalFilesystemFolder(config.source);
+	const destIsLocalFilesystem = isLocalFilesystemFolder(config.dest);
+	if (!sourceIsLocalFilesystem && !destIsLocalFilesystem) return {};
+	const sourceContext = config.dest.type === "b2" ? "upload" : "sync";
+	const destContext = config.source.type === "b2" ? "download" : "sync";
+	return {
+		...sourceIsLocalFilesystem ? { source: await resolveLocalRootContext(requireLocalRoot(config.source, "source", sourceContext)) } : {},
+		...destIsLocalFilesystem ? { dest: await resolveLocalRootContext(requireLocalRoot(config.dest, "destination", destContext)) } : {}
+	};
+}
+async function resolveLocalRootContext(root) {
+	const { realpath, stat } = await import("node:fs/promises");
+	const { resolve } = await import("node:path");
+	const safeRoot = resolve(root);
+	const realPath = await realpath(safeRoot).catch((err) => {
+		if (isNotFoundError(err)) return safeRoot;
+		throw err;
+	});
+	const stats = await stat(realPath).catch((err) => {
+		if (isNotFoundError(err)) return void 0;
+		throw err;
+	});
+	if (stats !== void 0 && !stats.isDirectory()) throw new Error("Local sync root is not a directory");
+	return {
+		root: safeRoot,
+		realPath,
+		...stats === void 0 ? {} : { identity: {
+			deviceId: stats.dev,
+			inode: stats.ino
+		} }
+	};
+}
+function isLocalFilesystemFolder(folder) {
+	return folder?.type === "local" && isLocalFilesystemRoot(folder);
+}
+/**
+* Narrows a setting to SSE-C; non-SSE-C source settings need no key on read.
+*
+* @param setting - Provider-supplied encryption setting, or undefined.
+*
+* @returns The SSE-C setting when one is provided; otherwise undefined.
+*/
+function toSseCEncryptionSetting(setting) {
+	if (setting?.mode !== "SSE-C") return void 0;
+	return setting;
+}
+/**
+* Returns a download key from SSE-C settings; non-SSE-C downloads need no key.
+*
+* @param setting - Provider-supplied encryption setting, or undefined.
+*
+* @returns A download key for SSE-C files; otherwise undefined.
+*/
+function toSseCDownloadKey(setting) {
+	return toSseCEncryptionSetting(setting);
+}
+/**
+* Creates a configured sync engine wired to the bucket and paths in the given config.
+*
+* For sync operations that may need to remove destination-only files (the
+* `keepMode: 'delete'` policy), the factory reads the destination
+* bucket's cached `fileLockConfiguration` once so `removeOrphan` can
+* dispatch to either `hide` (locked buckets) or `deleteFileVersion`
+* (vanilla buckets) without a per-file branch. The cache is whatever
+* `client.listBuckets()` or `client.createBucket()` returned — callers
+* who flipped lock state mid-sync (rare) should refresh before
+* synchronize().
+*
+* @param config - Synchronizer configuration containing source, destination, and options.
+* @param localRootContexts - Resolved filesystem roots captured before action creation.
+*
+* @returns An action factory bound to the provided configuration.
+*/
+function createActionFactory(config, localRootContexts) {
+	const upConfig = config;
+	const downConfig = config;
+	const uploadPrefix = asRawB2KeyPrefix(upConfig.prefix ?? b2FolderRawPrefix(config.dest) ?? "");
+	const sourceB2Prefix = b2FolderRawPrefix(config.source);
+	const bucketIsLocked = (upConfig.bucket ?? downConfig.bucket)?.info?.fileLockConfiguration?.value?.isFileLockEnabled ?? false;
+	const factory = {
+		upload(source, dest) {
+			const bucket = upConfig.bucket;
+			assertBucket(bucket, "upload");
+			return new UploadAction(source.relativePath, source.absolutePath, source.size, async (absPath, relPath, signal) => {
+				const rootContext = localRootContexts.source;
+				const root = rootContext?.root ?? upConfig.source.root ?? "";
+				const fileName = dest !== void 0 ? validateB2SyncPathInPrefix(uploadPrefix, dest) : `${uploadPrefix}${relPath}`;
+				if (rootContext !== void 0) await assertLocalRootContextCurrent(rootContext, relPath, { allowSymlinkRoot: true });
+				const targetPath = rootContext === void 0 ? await resolveContainedLocalPath(root, source.relativePath, absPath) : await resolveContainedLocalPath(rootContext.realPath, source.relativePath);
+				throwIfAborted(signal);
+				const fileSource = await createValidatedUploadFileSource(source, targetPath);
+				throwIfAborted(signal);
+				const serverSideEncryption = config.options.encryptionProvider?.getSettingForUpload(fileName, fileSource.size);
+				await bucket.upload({
+					fileName,
+					source: fileSource,
+					...serverSideEncryption !== void 0 ? { serverSideEncryption } : {},
+					...signal !== void 0 ? { signal } : {}
+				});
+			});
+		},
+		download(source, scannedDest) {
+			const bucket = downConfig.bucket;
+			assertBucket(bucket, "download");
+			return new DownloadAction(source.relativePath, source.size, async (relPath, signal) => {
+				const rootContext = localRootContexts.dest;
+				const root = rootContext?.root ?? downConfig.dest.root ?? "";
+				safeRelativePathSegments(relPath);
+				const b2FileName = sourceB2Prefix === void 0 ? source.selectedVersion.fileName : validateB2SyncPathInPrefix(sourceB2Prefix, source, "read");
+				const idleTimeoutMillis = normalizeDownloadIdleTimeoutMillis(config.options.downloadIdleTimeoutMillis);
+				const expectedBytes = assertValidB2ContentLength(source.selectedVersion.contentLength);
+				if (rootContext !== void 0) await assertLocalRootContextCurrent(rootContext, relPath, { allowSymlinkRoot: false });
+				await ensureLocalSyncRootDirectory(root, relPath);
+				const serverSideEncryption = toSseCDownloadKey(config.options.encryptionProvider?.getSettingForDownload(source.selectedVersion));
+				const result = await bucket.file(b2FileName).downloadById(source.selectedVersion.fileId, {
+					...serverSideEncryption !== void 0 ? { serverSideEncryption } : {},
+					...signal !== void 0 ? { signal } : {}
+				});
+				try {
+					await writeLocalStreamInsideRoot(root, relPath, result.body, {
+						expectedBytes,
+						...scannedDest !== void 0 ? { expectedDestination: scannedDest } : {},
+						idleTimeoutMillis,
+						...signal !== void 0 ? { signal } : {}
+					});
+				} catch (err) {
+					await cancelReadableStreamBody(result.body, err);
+					throw err;
+				}
+			});
+		},
+		copy(source, destRelativePath) {
+			return copyToB2Key(source, `${uploadPrefix}${destRelativePath}`);
+		},
+		copyB2Path(source, dest) {
+			return copyToB2Key(source, validateB2SyncPathInPrefix(uploadPrefix, dest));
+		},
+		hide(path) {
+			const bucket = upConfig.bucket ?? downConfig.bucket;
+			assertBucket(bucket, "hide");
+			return new HideAction(path, async (_relPath, signal) => {
+				await bucket.hideFile(`${uploadPrefix}${path}`, signal === void 0 ? void 0 : { signal });
+			});
+		},
+		hideB2Path(path) {
+			const bucket = upConfig.bucket ?? downConfig.bucket;
+			assertBucket(bucket, "hide");
+			const b2FileName = validateB2SyncPathInPrefix(uploadPrefix, path);
+			return new HideAction(path.relativePath, async (_relPath, signal) => {
+				await bucket.hideFile(b2FileName, signal === void 0 ? void 0 : { signal });
+			});
+		},
+		deleteRemote(path) {
+			const bucket = upConfig.bucket ?? downConfig.bucket;
+			assertBucket(bucket, "delete");
+			const b2FileName = validateB2SyncPathInPrefix(uploadPrefix, path);
+			return new DeleteRemoteAction(path.relativePath, path.selectedVersion.fileId, async (fileId$1, _fileName, signal) => {
+				await bucket.deleteFileVersion(b2FileName, fileId(fileId$1), signal === void 0 ? void 0 : { signal });
+			});
+		},
+		deleteLocal(path) {
+			const rootContext = localRootContexts.dest;
+			const root = rootContext?.root ?? localSyncRoot(downConfig.dest);
+			return new DeleteLocalAction(path.relativePath, path.absolutePath, async (absPath, signal) => {
+				signal?.throwIfAborted();
+				if (absPath !== path.absolutePath) throw new Error(`Refusing to delete outside sync root: ${path.relativePath}`);
+				signal?.throwIfAborted();
+				try {
+					if (rootContext !== void 0) await assertLocalRootContextCurrent(rootContext, path.relativePath, { allowSymlinkRoot: false });
+					await deleteLocalFileInsideRoot(root, path);
+				} catch (err) {
+					if (isLocalDeleteSafetyError(err)) throw err;
+					throw new Error(`failed to delete local file: ${localFilesystemErrorReason(err)}`);
+				}
+			});
+		},
+		removeOrphan(dest) {
+			return bucketIsLocked ? factory.hideB2Path?.(dest) ?? factory.hide(dest.relativePath) : factory.deleteRemote(dest);
+		}
+	};
+	function copyToB2Key(source, targetPath) {
+		const bucket = upConfig.bucket;
+		assertBucket(bucket, "copy");
+		return new CopyAction(source.relativePath, source.size, async (_relPath, signal) => {
+			if (sourceB2Prefix !== void 0) validateB2SyncPathInPrefix(sourceB2Prefix, source, "read");
+			const destinationServerSideEncryption = config.options.encryptionProvider?.getSettingForUpload(targetPath, source.size);
+			const sourceServerSideEncryption = toSseCEncryptionSetting(config.options.encryptionProvider?.getSettingForDownload(source.selectedVersion));
+			await bucket.copyFile({
+				sourceFileId: source.selectedVersion.fileId,
+				fileName: targetPath,
+				...destinationServerSideEncryption !== void 0 ? { destinationServerSideEncryption } : {},
+				...sourceServerSideEncryption !== void 0 ? { sourceServerSideEncryption } : {},
+				...signal !== void 0 ? { signal } : {}
+			});
+		});
+	}
+	return factory;
+}
+async function createValidatedUploadFileSource(source, absolutePath) {
+	try {
+		const fileSource = await FileSource.fromPath(absolutePath);
+		await validateScannedLocalFile({
+			...source,
+			absolutePath
+		});
+		return fileSource;
+	} catch (err) {
+		throw normalizeLocalUploadSourceError(err);
+	}
+}
+function normalizeLocalUploadSourceError(err) {
+	if (err instanceof Error && err.message.startsWith("local file changed before upload")) return err;
+	const message = err instanceof Error ? err.message : String(err);
+	if (message.includes("not a regular file")) return /* @__PURE__ */ new Error("local file changed before upload: not a regular file");
+	if (message.includes("changed") || message.includes("modified")) return /* @__PURE__ */ new Error("local file changed before upload");
+	return /* @__PURE__ */ new Error(`local file changed before upload: ${sanitizeErrorReason(err)}`);
+}
+function localSyncRoot(folder) {
+	return folder?.type === "local" ? folder.root : "";
+}
+function b2FolderRawPrefix(folder) {
+	if (folder?.type !== "b2") return void 0;
+	const rawPrefix = folder.rawPrefix;
+	return typeof rawPrefix === "string" ? rawPrefix : void 0;
+}
+function validateB2SourcePairPrefix(pair, config) {
+	const [source] = pair;
+	if (config.source.type !== "b2" || source === null || !isB2SyncPath(source)) return;
+	const sourcePrefix = b2FolderRawPrefix(config.source);
+	if (sourcePrefix === void 0) return;
+	validateB2SyncPathInPrefix(sourcePrefix, source, "read");
+}
+function b2ReadableRawPrefixes(config) {
+	const prefixes = [];
+	const sourcePrefix = b2FolderRawPrefix(config.source);
+	if (config.source.type === "b2") prefixes.push(sourcePrefix ?? "");
+	const upConfig = config;
+	if (config.dest.type === "b2") prefixes.push(upConfig.prefix ?? b2FolderRawPrefix(config.dest) ?? "");
+	return [...new Set(prefixes.map((prefix) => asRawB2KeyPrefix(prefix)))];
+}
+function validateB2SyncPathInAnyPrefix(prefixes, path, operation) {
+	let firstError = /* @__PURE__ */ new Error(`Refusing to ${operation} B2 key: ${path.relativePath}`);
+	for (const prefix of prefixes) try {
+		return validateB2SyncPathInPrefix(prefix, path, operation);
+	} catch (err) {
+		if (err instanceof Error) firstError = err;
+	}
+	throw firstError;
+}
+function validateB2SyncPathInPrefix(prefix, path, operation = "mutate") {
+	const fileName = path.selectedVersion.fileName;
+	if (!fileName.startsWith(prefix)) throw new Error(`Refusing to ${operation} B2 key outside configured prefix: ${path.relativePath}`);
+	if (b2KeyToRelativePathUnderPrefix(prefix, fileName) !== path.relativePath) throw new Error(`Refusing to ${operation} mismatched B2 key for sync path: ${path.relativePath}`);
+	return fileName;
+}
+function isB2SyncPath(path) {
+	return "selectedVersion" in path;
+}
+function throwIfAborted(signal) {
+	if (signal?.aborted === true) throw signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+async function cancelReadableStreamBody(body, reason) {
+	if (body.locked) return;
+	try {
+		await body.cancel(reason);
+	} catch {}
+}
+async function assertLocalRootContextCurrent(context, relativePath, options) {
+	if (context.identity === void 0) return;
+	const { lstat, realpath, stat } = await import("node:fs/promises");
+	let currentRealPath;
+	try {
+		const rootLinkStats = await lstat(context.root);
+		if (!options.allowSymlinkRoot && rootLinkStats.isSymbolicLink()) throw new Error(`Refusing to access sync root through symlink: ${relativePath}`);
+		currentRealPath = await realpath(context.root);
+	} catch (err) {
+		if (err instanceof Error && err.message.startsWith("Refusing to access sync root")) throw err;
+		throw new Error(`Local sync root changed before filesystem action: ${relativePath}`);
+	}
+	if (currentRealPath !== context.realPath) throw new Error(`Local sync root changed before filesystem action: ${relativePath}`);
+	let currentStats;
+	try {
+		currentStats = await stat(context.realPath);
+	} catch {
+		throw new Error(`Local sync root changed before filesystem action: ${relativePath}`);
+	}
+	if (!currentStats.isDirectory() || currentStats.dev !== context.identity.deviceId || currentStats.ino !== context.identity.inode) throw new Error(`Local sync root changed before filesystem action: ${relativePath}`);
+}
+async function ensureLocalSyncRootDirectory(root, relativePath) {
+	if (root === "") throw new Error("Local sync root required for filesystem mutation");
+	const { lstat, mkdir } = await import("node:fs/promises");
+	const { resolve } = await import("node:path");
+	const safeRoot = resolve(root);
+	try {
+		const stats = await lstat(safeRoot);
+		if (stats.isSymbolicLink()) throw new Error(`Refusing to access sync root through symlink: ${relativePath}`);
+		if (!stats.isDirectory()) throw new Error(`Local sync root is not a directory: ${relativePath}`);
+		return;
+	} catch (error) {
+		if (!isNotFoundError(error)) throw error;
+	}
+	await mkdir(safeRoot, { recursive: true });
+	await assertLocalRootHasNoSymlink(safeRoot, relativePath);
+}
+function bufferScanEvent(buffer, event, direction, scanSide) {
+	if (event.type === "skip" && event.reason === "filesystem-error") buffer.fatalFilesystemErrorMessage ??= event.message;
+	if (sourceSkipMakesInventoryIncomplete(event, direction, scanSide)) buffer.sourceInventoryIncompleteMessage ??= sourceInventoryIncompleteMessage(direction);
+	if (buffer.events.length < MAX_BUFFERED_SCAN_EVENTS) buffer.events.push(event);
+	else buffer.dropped++;
+}
+function* drainScanEvents(buffer) {
+	while (buffer.events.length > 0) {
+		const event = buffer.events.shift();
+		if (event) yield event;
+	}
+	if (buffer.dropped > 0) {
+		yield {
+			type: "skip",
+			path: "",
+			size: 0,
+			reason: "scan-skip-overflow",
+			message: `${buffer.dropped} scanner skip event(s) were omitted after ${MAX_BUFFERED_SCAN_EVENTS} buffered diagnostics`
+		};
+		buffer.dropped = 0;
+	}
+}
+function scanHadFilesystemError(scanEvents) {
+	return scanEvents.fatalFilesystemErrorMessage !== void 0;
+}
+function sourceInventoryIncomplete(scanEvents) {
+	return scanEvents.sourceInventoryIncompleteMessage !== void 0;
+}
+function scanFilesystemError(scanEvents) {
+	return scanEvents.fatalFilesystemErrorMessage === void 0 ? void 0 : new Error(scanEvents.fatalFilesystemErrorMessage);
+}
+function sourceSkipMakesInventoryIncomplete(event, direction, scanSide) {
+	if (scanSide !== "source" || event.type !== "skip") return false;
+	if (direction === "local-to-b2") return event.reason === "unsafe-name" || event.reason === "stale-download-partial" || event.reason === "path-too-long-for-regexp";
+	if (direction === "b2-to-local" || direction === "b2-to-b2") return event.reason === "unsafe-name" || event.reason === "local-unsafe-name" || event.reason === "relative-path-collision" || event.reason === "local-path-collision" || event.reason === "path-too-long-for-regexp";
+	return false;
+}
+function sourceInventoryIncompleteMessage(direction) {
+	return direction === "local-to-b2" ? "not removed because the source scan skipped local paths" : "not removed because the source scan skipped unsafe B2 names";
+}
+function isLocalDeleteSafetyError(err) {
+	if (!(err instanceof Error)) return false;
+	return err.message === "Local sync root required for filesystem mutation" || err.message.startsWith("Local sync root changed before filesystem action: ") || err.message.startsWith("Refusing to ") || err.message.startsWith("Local sync root is not a directory: ") || err.message.startsWith("unsafe local delete path: ");
+}
+async function resolveContainedLocalPath(root, relativePath, absolutePath) {
+	if (root === "") throw new Error("Local sync root required for filesystem mutation");
+	const { isAbsolute, relative, resolve, sep } = await import("node:path");
+	const safeRoot = resolve(root);
+	const target = absolutePath === void 0 ? resolve(safeRoot, relativePath) : resolve(absolutePath);
+	const pathFromRoot = relative(safeRoot, target);
+	/* v8 ignore next -- defense-in-depth after prior no-follow and symlink checks. */
+	if (pathFromRoot === ".." || pathFromRoot.startsWith(`..${sep}`) || isAbsolute(pathFromRoot)) throw new Error(`Refusing to access path outside sync root: ${relativePath}`);
+	await assertLocalRootHasNoSymlink(safeRoot, relativePath);
+	await assertPathHasNoSymlinkComponents(safeRoot, pathFromRoot, relativePath);
+	return target;
+}
+async function assertLocalRootHasNoSymlink(safeRoot, relativePath) {
+	const { lstat } = await import("node:fs/promises");
+	try {
+		if ((await lstat(safeRoot)).isSymbolicLink()) throw new Error(`Refusing to access sync root through symlink: ${relativePath}`);
+	} catch (error) {
+		if (isNotFoundError(error)) return;
+		throw error;
+	}
+}
+async function assertPathHasNoSymlinkComponents(safeRoot, pathFromRoot, relativePath) {
+	if (pathFromRoot === "") return;
+	const { lstat } = await import("node:fs/promises");
+	const { join, sep } = await import("node:path");
+	let current = safeRoot;
+	for (const segment of pathFromRoot.split(sep)) {
+		current = join(current, segment);
+		let stats;
+		try {
+			stats = await lstat(current);
+		} catch (error) {
+			if (isNotFoundError(error)) return;
+			throw error;
+		}
+		if (stats.isSymbolicLink()) throw new Error(`Refusing to access path through symlink: ${relativePath}`);
+	}
+}
+function isNotFoundError(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+//#endregion
+export { synchronize, synchronizerTestHooks };
+
+//# sourceMappingURL=synchronizer.js.map