@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/sync/b2-sha1-reader.d.cts

@@ -0,0 +1,58 @@
+/**
+ * Reads one non-empty stream chunk with an idle timeout and optional abort signal.
+ * Empty chunks are not progress; too many consecutive empty chunks fail with the
+ * same stalled-read diagnostic used for pending reads.
+ *
+ * @param reader - Locked reader to read from.
+ * @param timeoutMillis - Idle timeout in milliseconds for this read.
+ * @param stalledMessage - Error message used when the read makes no progress.
+ * @param signal - Optional abort signal to observe while reading.
+ *
+ * @returns The next stream read result.
+ *
+ * @internal
+ */
+export declare function readStreamChunkWithTimeout(reader: ReadableStreamDefaultReader<Uint8Array>, timeoutMillis: number, stalledMessage: string, signal?: AbortSignal): Promise<ReadableStreamReadResult<Uint8Array>>;
+/**
+ * Hashes a B2 response body as SHA-1 with idle timeout, abort, and size checks.
+ *
+ * @param body - Response body stream to hash.
+ * @param signal - Optional abort signal to observe while reading.
+ * @param options - Optional timeout and byte-count limits.
+ *
+ * @returns The computed SHA-1 and number of bytes read.
+ *
+ * @internal
+ */
+export declare function hashReadableStreamSha1(body: ReadableStream<Uint8Array>, signal?: AbortSignal, options?: {
+    readonly idleTimeoutMillis: number;
+    readonly maxBytes: number;
+    readonly expectedBytes: number;
+}): Promise<{
+    readonly contentSha1: string;
+    readonly bytesRead: number;
+}>;
+/**
+ * Applies an absolute verification deadline while forwarding parent aborts.
+ *
+ * @param signal - Optional parent abort signal.
+ * @param timeoutMillis - Absolute deadline in milliseconds.
+ * @param run - Operation to run with the derived deadline signal.
+ *
+ * @returns The operation result.
+ *
+ * @internal
+ */
+export declare function withSha1VerificationDeadline<T>(signal: AbortSignal | undefined, timeoutMillis: number, run: (signal: AbortSignal) => Promise<T>): Promise<T>;
+/**
+ * Bounds B2 SHA-1 verification downloads to the selected object's size and optional ceiling.
+ *
+ * @param contentLength - Selected B2 object byte length.
+ * @param ceiling - Optional lower verification budget.
+ *
+ * @returns The byte budget to enforce.
+ *
+ * @internal
+ */
+export declare function normalizeSha1VerificationMaxBytes(contentLength: number, ceiling: number | undefined): number;
+//# sourceMappingURL=b2-sha1-reader.d.ts.map

package/dist/sync/b2-sha1-reader.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"b2-sha1-reader.d.ts","sourceRoot":"","sources":["../../src/sync/b2-sha1-reader.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;GAaG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,2BAA2B,CAAC,UAAU,CAAC,EAC/C,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,wBAAwB,CAAC,UAAU,CAAC,CAAC,CAe/C;AA2CD;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B,GACA,OAAO,CAAC;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAgCvE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,4BAA4B,CAAC,CAAC,EAClD,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GACvC,OAAO,CAAC,CAAC,CAAC,CAsBZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,iCAAiC,CAC/C,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,CAKR"}

package/dist/sync/b2-sha1-reader.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Reads one non-empty stream chunk with an idle timeout and optional abort signal.
+ * Empty chunks are not progress; too many consecutive empty chunks fail with the
+ * same stalled-read diagnostic used for pending reads.
+ *
+ * @param reader - Locked reader to read from.
+ * @param timeoutMillis - Idle timeout in milliseconds for this read.
+ * @param stalledMessage - Error message used when the read makes no progress.
+ * @param signal - Optional abort signal to observe while reading.
+ *
+ * @returns The next stream read result.
+ *
+ * @internal
+ */
+export declare function readStreamChunkWithTimeout(reader: ReadableStreamDefaultReader<Uint8Array>, timeoutMillis: number, stalledMessage: string, signal?: AbortSignal): Promise<ReadableStreamReadResult<Uint8Array>>;
+/**
+ * Hashes a B2 response body as SHA-1 with idle timeout, abort, and size checks.
+ *
+ * @param body - Response body stream to hash.
+ * @param signal - Optional abort signal to observe while reading.
+ * @param options - Optional timeout and byte-count limits.
+ *
+ * @returns The computed SHA-1 and number of bytes read.
+ *
+ * @internal
+ */
+export declare function hashReadableStreamSha1(body: ReadableStream<Uint8Array>, signal?: AbortSignal, options?: {
+    readonly idleTimeoutMillis: number;
+    readonly maxBytes: number;
+    readonly expectedBytes: number;
+}): Promise<{
+    readonly contentSha1: string;
+    readonly bytesRead: number;
+}>;
+/**
+ * Applies an absolute verification deadline while forwarding parent aborts.
+ *
+ * @param signal - Optional parent abort signal.
+ * @param timeoutMillis - Absolute deadline in milliseconds.
+ * @param run - Operation to run with the derived deadline signal.
+ *
+ * @returns The operation result.
+ *
+ * @internal
+ */
+export declare function withSha1VerificationDeadline<T>(signal: AbortSignal | undefined, timeoutMillis: number, run: (signal: AbortSignal) => Promise<T>): Promise<T>;
+/**
+ * Bounds B2 SHA-1 verification downloads to the selected object's size and optional ceiling.
+ *
+ * @param contentLength - Selected B2 object byte length.
+ * @param ceiling - Optional lower verification budget.
+ *
+ * @returns The byte budget to enforce.
+ *
+ * @internal
+ */
+export declare function normalizeSha1VerificationMaxBytes(contentLength: number, ceiling: number | undefined): number;
+//# sourceMappingURL=b2-sha1-reader.d.ts.map

package/dist/sync/b2-sha1-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"b2-sha1-reader.d.ts","sourceRoot":"","sources":["../../src/sync/b2-sha1-reader.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;GAaG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,2BAA2B,CAAC,UAAU,CAAC,EAC/C,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,wBAAwB,CAAC,UAAU,CAAC,CAAC,CAe/C;AA2CD;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B,GACA,OAAO,CAAC;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAgCvE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,4BAA4B,CAAC,CAAC,EAClD,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GACvC,OAAO,CAAC,CAAC,CAAC,CAsBZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,iCAAiC,CAC/C,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,CAKR"}

package/dist/sync/b2-sha1-reader.js

@@ -0,0 +1,145 @@
+import { IncrementalSha1 } from "../streams/hash.js";
+import { normalizeSha1TimeoutMillis } from "./sha1-options.js";
+//#region src/sync/b2-sha1-reader.ts
+var MAX_CONSECUTIVE_EMPTY_READ_CHUNKS = 1024;
+/**
+* Reads one non-empty stream chunk with an idle timeout and optional abort signal.
+* Empty chunks are not progress; too many consecutive empty chunks fail with the
+* same stalled-read diagnostic used for pending reads.
+*
+* @param reader - Locked reader to read from.
+* @param timeoutMillis - Idle timeout in milliseconds for this read.
+* @param stalledMessage - Error message used when the read makes no progress.
+* @param signal - Optional abort signal to observe while reading.
+*
+* @returns The next stream read result.
+*
+* @internal
+*/
+async function readStreamChunkWithTimeout(reader, timeoutMillis, stalledMessage, signal) {
+	let emptyChunks = 0;
+	while (true) {
+		const result = await readRawStreamChunkWithTimeout(reader, timeoutMillis, stalledMessage, signal);
+		if (result.done || result.value.byteLength > 0) return result;
+		emptyChunks += 1;
+		if (emptyChunks > MAX_CONSECUTIVE_EMPTY_READ_CHUNKS) throw new Error(stalledMessage);
+	}
+}
+async function readRawStreamChunkWithTimeout(reader, timeoutMillis, stalledMessage, signal) {
+	signal?.throwIfAborted();
+	let timeout;
+	let removeAbortListener;
+	const readPromise = reader.read();
+	const timeoutPromise = timeoutMillis === Number.POSITIVE_INFINITY ? void 0 : new Promise((_, reject) => {
+		timeout = setTimeout(() => {
+			reject(new Error(stalledMessage));
+		}, timeoutMillis);
+	});
+	const abortPromise = signal === void 0 ? void 0 : new Promise((_, reject) => {
+		const onAbort = () => reject(signal.reason ?? /* @__PURE__ */ new Error("aborted"));
+		signal.addEventListener("abort", onAbort, { once: true });
+		removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+	});
+	try {
+		if (timeoutPromise === void 0 && abortPromise === void 0) return await readPromise;
+		const candidates = [readPromise];
+		if (timeoutPromise !== void 0) candidates.push(timeoutPromise);
+		if (abortPromise !== void 0) candidates.push(abortPromise);
+		return await Promise.race(candidates);
+	} finally {
+		if (timeout !== void 0) clearTimeout(timeout);
+		removeAbortListener?.();
+		readPromise.catch(() => {});
+	}
+}
+/**
+* Hashes a B2 response body as SHA-1 with idle timeout, abort, and size checks.
+*
+* @param body - Response body stream to hash.
+* @param signal - Optional abort signal to observe while reading.
+* @param options - Optional timeout and byte-count limits.
+*
+* @returns The computed SHA-1 and number of bytes read.
+*
+* @internal
+*/
+async function hashReadableStreamSha1(body, signal, options) {
+	const hash = new IncrementalSha1();
+	const reader = body.getReader();
+	const idleTimeoutMillis = options?.idleTimeoutMillis ?? normalizeSha1TimeoutMillis(void 0);
+	const maxBytes = options?.maxBytes ?? Number.POSITIVE_INFINITY;
+	const expectedBytes = options?.expectedBytes;
+	let bytesRead = 0;
+	try {
+		while (true) {
+			const { done, value } = await readStreamChunkWithTimeout(reader, idleTimeoutMillis, `sha1 B2 read stalled for ${idleTimeoutMillis} ms`, signal);
+			if (done) break;
+			bytesRead += value.byteLength;
+			if (bytesRead > maxBytes) throw new Error(`sha1 B2 read exceeded ${maxBytes} byte verification budget`);
+			await hash.update(value);
+		}
+		if (expectedBytes !== void 0 && bytesRead !== expectedBytes) throw new Error(`sha1 B2 read ended after ${bytesRead} bytes, expected ${expectedBytes}`);
+		return {
+			contentSha1: await hash.digest(),
+			bytesRead
+		};
+	} catch (err) {
+		reader.cancel(err).catch(() => {});
+		throw err;
+	} finally {
+		reader.releaseLock();
+	}
+}
+/**
+* Applies an absolute verification deadline while forwarding parent aborts.
+*
+* @param signal - Optional parent abort signal.
+* @param timeoutMillis - Absolute deadline in milliseconds.
+* @param run - Operation to run with the derived deadline signal.
+*
+* @returns The operation result.
+*
+* @internal
+*/
+async function withSha1VerificationDeadline(signal, timeoutMillis, run) {
+	const controller = new AbortController();
+	const abortFromParent = () => controller.abort(signal?.reason);
+	if (signal?.aborted) abortFromParent();
+	signal?.addEventListener("abort", abortFromParent, { once: true });
+	let timeout;
+	const timeoutPromise = new Promise((_, reject) => {
+		timeout = setTimeout(() => {
+			const error = /* @__PURE__ */ new Error(`sha1 B2 verification exceeded ${timeoutMillis} ms`);
+			controller.abort(error);
+			reject(error);
+		}, timeoutMillis);
+	});
+	const runPromise = run(controller.signal);
+	try {
+		return await Promise.race([runPromise, timeoutPromise]);
+	} finally {
+		if (timeout !== void 0) clearTimeout(timeout);
+		signal?.removeEventListener("abort", abortFromParent);
+		runPromise.catch(() => {});
+	}
+}
+/**
+* Bounds B2 SHA-1 verification downloads to the selected object's size and optional ceiling.
+*
+* @param contentLength - Selected B2 object byte length.
+* @param ceiling - Optional lower verification budget.
+*
+* @returns The byte budget to enforce.
+*
+* @internal
+*/
+function normalizeSha1VerificationMaxBytes(contentLength, ceiling) {
+	const contentBudget = Math.max(0, Math.floor(contentLength));
+	if (ceiling === void 0) return contentBudget;
+	if (!Number.isFinite(ceiling) || ceiling < 0) return contentBudget;
+	return Math.min(contentBudget, Math.floor(ceiling));
+}
+//#endregion
+export { hashReadableStreamSha1, normalizeSha1VerificationMaxBytes, readStreamChunkWithTimeout, withSha1VerificationDeadline };
+
+//# sourceMappingURL=b2-sha1-reader.js.map

package/dist/sync/b2-sha1-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"b2-sha1-reader.js","names":[],"sources":["../../src/sync/b2-sha1-reader.ts"],"sourcesContent":["import { IncrementalSha1 } from '../streams/hash.ts'\nimport { normalizeSha1TimeoutMillis } from './sha1-options.ts'\n\nconst MAX_CONSECUTIVE_EMPTY_READ_CHUNKS = 1024\n\n/**\n * Reads one non-empty stream chunk with an idle timeout and optional abort signal.\n * Empty chunks are not progress; too many consecutive empty chunks fail with the\n * same stalled-read diagnostic used for pending reads.\n *\n * @param reader - Locked reader to read from.\n * @param timeoutMillis - Idle timeout in milliseconds for this read.\n * @param stalledMessage - Error message used when the read makes no progress.\n * @param signal - Optional abort signal to observe while reading.\n *\n * @returns The next stream read result.\n *\n * @internal\n */\nexport async function readStreamChunkWithTimeout(\n  reader: ReadableStreamDefaultReader<Uint8Array>,\n  timeoutMillis: number,\n  stalledMessage: string,\n  signal?: AbortSignal,\n): Promise<ReadableStreamReadResult<Uint8Array>> {\n  let emptyChunks = 0\n  while (true) {\n    const result = await readRawStreamChunkWithTimeout(\n      reader,\n      timeoutMillis,\n      stalledMessage,\n      signal,\n    )\n    if (result.done || result.value.byteLength > 0) return result\n    emptyChunks += 1\n    if (emptyChunks > MAX_CONSECUTIVE_EMPTY_READ_CHUNKS) {\n      throw new Error(stalledMessage)\n    }\n  }\n}\n\nasync function readRawStreamChunkWithTimeout(\n  reader: ReadableStreamDefaultReader<Uint8Array>,\n  timeoutMillis: number,\n  stalledMessage: string,\n  signal?: AbortSignal,\n): Promise<ReadableStreamReadResult<Uint8Array>> {\n  signal?.throwIfAborted()\n\n  let timeout: ReturnType<typeof setTimeout> | undefined\n  let removeAbortListener: (() => void) | undefined\n  const readPromise = reader.read()\n  const timeoutPromise =\n    timeoutMillis === Number.POSITIVE_INFINITY\n      ? undefined\n      : new Promise<never>((_, reject) => {\n          timeout = setTimeout(() => {\n            reject(new Error(stalledMessage))\n          }, timeoutMillis)\n        })\n  const abortPromise =\n    signal === undefined\n      ? undefined\n      : new Promise<never>((_, reject) => {\n          const onAbort = () => reject(signal.reason ?? new Error('aborted'))\n          signal.addEventListener('abort', onAbort, { once: true })\n          removeAbortListener = () => signal.removeEventListener('abort', onAbort)\n        })\n\n  try {\n    if (timeoutPromise === undefined && abortPromise === undefined) return await readPromise\n    const candidates = [readPromise]\n    if (timeoutPromise !== undefined) candidates.push(timeoutPromise)\n    if (abortPromise !== undefined) candidates.push(abortPromise)\n    return await Promise.race(candidates)\n  } finally {\n    if (timeout !== undefined) clearTimeout(timeout)\n    removeAbortListener?.()\n    void readPromise.catch(() => {})\n  }\n}\n\n/**\n * Hashes a B2 response body as SHA-1 with idle timeout, abort, and size checks.\n *\n * @param body - Response body stream to hash.\n * @param signal - Optional abort signal to observe while reading.\n * @param options - Optional timeout and byte-count limits.\n *\n * @returns The computed SHA-1 and number of bytes read.\n *\n * @internal\n */\nexport async function hashReadableStreamSha1(\n  body: ReadableStream<Uint8Array>,\n  signal?: AbortSignal,\n  options?: {\n    readonly idleTimeoutMillis: number\n    readonly maxBytes: number\n    readonly expectedBytes: number\n  },\n): Promise<{ readonly contentSha1: string; readonly bytesRead: number }> {\n  const hash = new IncrementalSha1()\n  const reader = body.getReader()\n  const idleTimeoutMillis = options?.idleTimeoutMillis ?? normalizeSha1TimeoutMillis(undefined)\n  const maxBytes = options?.maxBytes ?? Number.POSITIVE_INFINITY\n  const expectedBytes = options?.expectedBytes\n  let bytesRead = 0\n  try {\n    while (true) {\n      const { done, value } = await readStreamChunkWithTimeout(\n        reader,\n        idleTimeoutMillis,\n        `sha1 B2 read stalled for ${idleTimeoutMillis} ms`,\n        signal,\n      )\n      if (done) break\n      bytesRead += value.byteLength\n      if (bytesRead > maxBytes) {\n        throw new Error(`sha1 B2 read exceeded ${maxBytes} byte verification budget`)\n      }\n      await hash.update(value)\n    }\n    if (expectedBytes !== undefined && bytesRead !== expectedBytes) {\n      throw new Error(`sha1 B2 read ended after ${bytesRead} bytes, expected ${expectedBytes}`)\n    }\n    return { contentSha1: await hash.digest(), bytesRead }\n  } catch (err) {\n    void reader.cancel(err).catch(() => {})\n    throw err\n  } finally {\n    reader.releaseLock()\n  }\n}\n\n/**\n * Applies an absolute verification deadline while forwarding parent aborts.\n *\n * @param signal - Optional parent abort signal.\n * @param timeoutMillis - Absolute deadline in milliseconds.\n * @param run - Operation to run with the derived deadline signal.\n *\n * @returns The operation result.\n *\n * @internal\n */\nexport async function withSha1VerificationDeadline<T>(\n  signal: AbortSignal | undefined,\n  timeoutMillis: number,\n  run: (signal: AbortSignal) => Promise<T>,\n): Promise<T> {\n  const controller = new AbortController()\n  const abortFromParent = () => controller.abort(signal?.reason)\n  if (signal?.aborted) abortFromParent()\n  signal?.addEventListener('abort', abortFromParent, { once: true })\n\n  let timeout: ReturnType<typeof setTimeout> | undefined\n  const timeoutPromise = new Promise<never>((_, reject) => {\n    timeout = setTimeout(() => {\n      const error = new Error(`sha1 B2 verification exceeded ${timeoutMillis} ms`)\n      controller.abort(error)\n      reject(error)\n    }, timeoutMillis)\n  })\n  const runPromise = run(controller.signal)\n  try {\n    return await Promise.race([runPromise, timeoutPromise])\n  } finally {\n    if (timeout !== undefined) clearTimeout(timeout)\n    signal?.removeEventListener('abort', abortFromParent)\n    void runPromise.catch(() => {})\n  }\n}\n\n/**\n * Bounds B2 SHA-1 verification downloads to the selected object's size and optional ceiling.\n *\n * @param contentLength - Selected B2 object byte length.\n * @param ceiling - Optional lower verification budget.\n *\n * @returns The byte budget to enforce.\n *\n * @internal\n */\nexport function normalizeSha1VerificationMaxBytes(\n  contentLength: number,\n  ceiling: number | undefined,\n): number {\n  const contentBudget = Math.max(0, Math.floor(contentLength))\n  if (ceiling === undefined) return contentBudget\n  if (!Number.isFinite(ceiling) || ceiling < 0) return contentBudget\n  return Math.min(contentBudget, Math.floor(ceiling))\n}\n"],"mappings":";;;AAGA,IAAM,oCAAoC;;;;;;;;;;;;;;;AAgB1C,eAAsB,2BACpB,QACA,eACA,gBACA,QAC+C;CAC/C,IAAI,cAAc;CAClB,OAAO,MAAM;EACX,MAAM,SAAS,MAAM,8BACnB,QACA,eACA,gBACA,MACF;EACA,IAAI,OAAO,QAAQ,OAAO,MAAM,aAAa,GAAG,OAAO;EACvD,eAAe;EACf,IAAI,cAAc,mCAChB,MAAM,IAAI,MAAM,cAAc;CAElC;AACF;AAEA,eAAe,8BACb,QACA,eACA,gBACA,QAC+C;CAC/C,QAAQ,eAAe;CAEvB,IAAI;CACJ,IAAI;CACJ,MAAM,cAAc,OAAO,KAAK;CAChC,MAAM,iBACJ,kBAAkB,OAAO,oBACrB,KAAA,IACA,IAAI,SAAgB,GAAG,WAAW;EAChC,UAAU,iBAAiB;GACzB,OAAO,IAAI,MAAM,cAAc,CAAC;EAClC,GAAG,aAAa;CAClB,CAAC;CACP,MAAM,eACJ,WAAW,KAAA,IACP,KAAA,IACA,IAAI,SAAgB,GAAG,WAAW;EAChC,MAAM,gBAAgB,OAAO,OAAO,0BAAU,IAAI,MAAM,SAAS,CAAC;EAClE,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EACxD,4BAA4B,OAAO,oBAAoB,SAAS,OAAO;CACzE,CAAC;CAEP,IAAI;EACF,IAAI,mBAAmB,KAAA,KAAa,iBAAiB,KAAA,GAAW,OAAO,MAAM;EAC7E,MAAM,aAAa,CAAC,WAAW;EAC/B,IAAI,mBAAmB,KAAA,GAAW,WAAW,KAAK,cAAc;EAChE,IAAI,iBAAiB,KAAA,GAAW,WAAW,KAAK,YAAY;EAC5D,OAAO,MAAM,QAAQ,KAAK,UAAU;CACtC,UAAU;EACR,IAAI,YAAY,KAAA,GAAW,aAAa,OAAO;EAC/C,sBAAsB;EACtB,YAAiB,YAAY,CAAC,CAAC;CACjC;AACF;;;;;;;;;;;;AAaA,eAAsB,uBACpB,MACA,QACA,SAKuE;CACvE,MAAM,OAAO,IAAI,gBAAgB;CACjC,MAAM,SAAS,KAAK,UAAU;CAC9B,MAAM,oBAAoB,SAAS,qBAAqB,2BAA2B,KAAA,CAAS;CAC5F,MAAM,WAAW,SAAS,YAAY,OAAO;CAC7C,MAAM,gBAAgB,SAAS;CAC/B,IAAI,YAAY;CAChB,IAAI;EACF,OAAO,MAAM;GACX,MAAM,EAAE,MAAM,UAAU,MAAM,2BAC5B,QACA,mBACA,4BAA4B,kBAAkB,MAC9C,MACF;GACA,IAAI,MAAM;GACV,aAAa,MAAM;GACnB,IAAI,YAAY,UACd,MAAM,IAAI,MAAM,yBAAyB,SAAS,0BAA0B;GAE9E,MAAM,KAAK,OAAO,KAAK;EACzB;EACA,IAAI,kBAAkB,KAAA,KAAa,cAAc,eAC/C,MAAM,IAAI,MAAM,4BAA4B,UAAU,mBAAmB,eAAe;EAE1F,OAAO;GAAE,aAAa,MAAM,KAAK,OAAO;GAAG;EAAU;CACvD,SAAS,KAAK;EACZ,OAAY,OAAO,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC;EACtC,MAAM;CACR,UAAU;EACR,OAAO,YAAY;CACrB;AACF;;;;;;;;;;;;AAaA,eAAsB,6BACpB,QACA,eACA,KACY;CACZ,MAAM,aAAa,IAAI,gBAAgB;CACvC,MAAM,wBAAwB,WAAW,MAAM,QAAQ,MAAM;CAC7D,IAAI,QAAQ,SAAS,gBAAgB;CACrC,QAAQ,iBAAiB,SAAS,iBAAiB,EAAE,MAAM,KAAK,CAAC;CAEjE,IAAI;CACJ,MAAM,iBAAiB,IAAI,SAAgB,GAAG,WAAW;EACvD,UAAU,iBAAiB;GACzB,MAAM,wBAAQ,IAAI,MAAM,iCAAiC,cAAc,IAAI;GAC3E,WAAW,MAAM,KAAK;GACtB,OAAO,KAAK;EACd,GAAG,aAAa;CAClB,CAAC;CACD,MAAM,aAAa,IAAI,WAAW,MAAM;CACxC,IAAI;EACF,OAAO,MAAM,QAAQ,KAAK,CAAC,YAAY,cAAc,CAAC;CACxD,UAAU;EACR,IAAI,YAAY,KAAA,GAAW,aAAa,OAAO;EAC/C,QAAQ,oBAAoB,SAAS,eAAe;EACpD,WAAgB,YAAY,CAAC,CAAC;CAChC;AACF;;;;;;;;;;;AAYA,SAAgB,kCACd,eACA,SACQ;CACR,MAAM,gBAAgB,KAAK,IAAI,GAAG,KAAK,MAAM,aAAa,CAAC;CAC3D,IAAI,YAAY,KAAA,GAAW,OAAO;CAClC,IAAI,CAAC,OAAO,SAAS,OAAO,KAAK,UAAU,GAAG,OAAO;CACrD,OAAO,KAAK,IAAI,eAAe,KAAK,MAAM,OAAO,CAAC;AACpD"}

package/dist/sync/download-staging.cjs

@@ -0,0 +1,265 @@
+const require_path_safety = require("./path-safety.cjs");
+//#region src/sync/download-staging.ts
+/** @internal */
+var DOWNLOAD_STAGING_DIRECTORY_NAME = ".b2sdk-download-staging";
+/** @internal */
+var DOWNLOAD_STAGING_MARKER_NAME = ".b2sdk-staging-marker.partial";
+var CANONICAL_DOWNLOAD_STAGING_DIRECTORY_NAME = canonicalLocalFilesystemSegment(DOWNLOAD_STAGING_DIRECTORY_NAME);
+var DOWNLOAD_STAGING_ENTRY_SUFFIX = ".download";
+var STALE_DOWNLOAD_STAGING_AGE_MS = 1440 * 60 * 1e3;
+var MAX_STAGING_CLEANUP_CONCURRENCY = 8;
+var MAX_CLEANUP_WARNING_ENTRIES = 3;
+/** @internal */
+var DOWNLOAD_STAGING_ACTIVITY_ENTRY_LIMIT = 1024;
+var reapedManagedDirectories = /* @__PURE__ */ new Map();
+/**
+* Checks whether a single path segment matches the SDK-managed staging directory name.
+* @param segment - Candidate path segment.
+*
+* @returns True when the segment is the reserved staging directory name under
+* local filesystem canonicalization.
+*
+* @internal
+*/
+function isDownloadStagingDirectorySegment(segment) {
+	return segment !== void 0 && canonicalLocalFilesystemSegment(segment) === CANONICAL_DOWNLOAD_STAGING_DIRECTORY_NAME;
+}
+/**
+* Creates a private SDK-managed staging directory under a local sync root.
+* @param rootRealPath - Resolved local sync root path.
+* @param path - Node path module used for platform-specific path operations.
+* @param randomUUID - UUID provider used to create unique staging entries.
+* @param statForDeviceCheck - Stat function used to verify filesystem devices.
+* @param beforeStagingMarkerWrite - Test hook called before marker creation.
+*
+* @returns The resolved staging directory path.
+*
+* @internal
+*/
+async function createDownloadStagingDirectory(rootRealPath, path, randomUUID, statForDeviceCheck, beforeStagingMarkerWrite) {
+	const { chmod, lstat, mkdir, readdir, realpath, rm } = await import("node:fs/promises");
+	const managedDirectory = path.join(rootRealPath, DOWNLOAD_STAGING_DIRECTORY_NAME);
+	try {
+		await mkdir(managedDirectory, { mode: PRIVATE_DOWNLOAD_DIRECTORY_MODE });
+	} catch (err) {
+		if (!require_path_safety.hasErrorCode(err, "EEXIST")) throw err;
+	}
+	if (!(await lstat(managedDirectory)).isDirectory()) throw new Error(`unsafe local destination path: ${DOWNLOAD_STAGING_DIRECTORY_NAME} is not a directory`);
+	const realManagedDirectory = await realpath(managedDirectory);
+	require_path_safety.assertPathInsideRoot(rootRealPath, realManagedDirectory, path);
+	await assertDownloadPathSameDevice(rootRealPath, realManagedDirectory, statForDeviceCheck, "unsafe local destination path: cannot stage download across filesystems");
+	if (!await isManagedDownloadStagingRoot(realManagedDirectory)) {
+		if ((await readdir(realManagedDirectory)).length > 0 && !await isManagedDownloadStagingRoot(realManagedDirectory)) throw new Error(`unsafe local destination path: ${DOWNLOAD_STAGING_DIRECTORY_NAME} is reserved for SDK download staging`);
+	}
+	await beforeStagingMarkerWrite?.(realManagedDirectory);
+	await writeStagingMarker(realManagedDirectory, path);
+	/* v8 ignore next -- best-effort chmod */
+	await chmod(realManagedDirectory, PRIVATE_DOWNLOAD_DIRECTORY_MODE).catch(() => {});
+	await reapStaleDownloadStagingDirectoriesOnce(realManagedDirectory, path, Date.now());
+	const stagingDirectory = path.join(realManagedDirectory, `${Date.now()}-${randomUUID()}${DOWNLOAD_STAGING_ENTRY_SUFFIX}`);
+	await mkdir(stagingDirectory, { mode: PRIVATE_DOWNLOAD_DIRECTORY_MODE });
+	/* v8 ignore next -- best-effort chmod */
+	await chmod(stagingDirectory, PRIVATE_DOWNLOAD_DIRECTORY_MODE).catch(() => {});
+	try {
+		const realStagingDirectory = await realpath(stagingDirectory);
+		require_path_safety.assertPathInsideRoot(realManagedDirectory, realStagingDirectory, path);
+		await assertDownloadPathSameDevice(rootRealPath, realStagingDirectory, statForDeviceCheck, "unsafe local destination path: cannot stage download across filesystems");
+		await beforeStagingMarkerWrite?.(realStagingDirectory);
+		await writeStagingMarker(realStagingDirectory, path);
+		return realStagingDirectory;
+	} catch (err) {
+		/* v8 ignore next -- best-effort cleanup */
+		await rm(stagingDirectory, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+		throw err;
+	}
+}
+/**
+* Returns true when a scan-root entry is an SDK-managed download staging root.
+* @param directory - Candidate directory to inspect.
+*
+* @returns True when the directory contains SDK staging markers.
+*
+* @internal
+*/
+async function isManagedDownloadStagingRoot(directory) {
+	const { lstat, readdir } = await import("node:fs/promises");
+	const path = await import("node:path");
+	try {
+		if ((await lstat(path.join(directory, ".b2sdk-staging-marker.partial"))).isFile()) return true;
+	} catch (err) {
+		if (!require_path_safety.hasErrorCode(err, "ENOENT")) return false;
+	}
+	let entries;
+	try {
+		entries = await readdir(directory, { withFileTypes: true });
+	} catch {
+		return false;
+	}
+	for (const entry of entries) {
+		if (!entry.isDirectory() || !entry.name.endsWith(DOWNLOAD_STAGING_ENTRY_SUFFIX)) continue;
+		try {
+			if ((await lstat(path.join(directory, entry.name, ".b2sdk-staging-marker.partial"))).isFile()) return true;
+		} catch {}
+	}
+	return false;
+}
+var PRIVATE_DOWNLOAD_FILE_MODE = 384;
+var PRIVATE_DOWNLOAD_DIRECTORY_MODE = 448;
+async function writeStagingMarker(directory, path) {
+	const { constants } = await import("node:fs");
+	const { lstat, open } = await import("node:fs/promises");
+	const markerPath = path.join(directory, DOWNLOAD_STAGING_MARKER_NAME);
+	let handle;
+	try {
+		handle = await open(markerPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | require_path_safety.noFollowFlag(constants), PRIVATE_DOWNLOAD_FILE_MODE);
+		/* v8 ignore next -- best-effort chmod */
+		await handle.chmod(PRIVATE_DOWNLOAD_FILE_MODE).catch(() => {});
+	} catch (err) {
+		if (require_path_safety.hasErrorCode(err, "EEXIST") || require_path_safety.hasErrorCode(err, "ELOOP")) {
+			if ((await lstat(markerPath).catch(() => void 0))?.isFile() === true) return;
+			throw new Error("unsafe local destination path: staging marker is not a regular file");
+		}
+		throw err;
+	} finally {
+		/* v8 ignore next -- best-effort close */
+		await handle?.close().catch(() => {});
+	}
+}
+/**
+* Verifies that a candidate path is on the same filesystem device as the root.
+* @param rootRealPath - Resolved local sync root path.
+* @param candidateRealPath - Resolved candidate path to compare.
+* @param statForDeviceCheck - Stat function used to read device IDs.
+* @param message - Error message used when devices differ.
+*
+* @internal
+*/
+async function assertDownloadPathSameDevice(rootRealPath, candidateRealPath, statForDeviceCheck, message) {
+	const [rootStats, candidateStats] = await Promise.all([statForDeviceCheck(rootRealPath), statForDeviceCheck(candidateRealPath)]);
+	if (rootStats.dev !== candidateStats.dev) throw new Error(message);
+}
+async function reapStaleDownloadStagingDirectoriesOnce(managedDirectory, path, nowMillis) {
+	const previous = reapedManagedDirectories.get(managedDirectory);
+	if (previous !== void 0) {
+		await previous;
+		return;
+	}
+	const next = reapStaleDownloadStagingDirectories(managedDirectory, path, nowMillis).finally(() => {
+		if (reapedManagedDirectories.get(managedDirectory) === next) reapedManagedDirectories.delete(managedDirectory);
+	});
+	reapedManagedDirectories.set(managedDirectory, next);
+	await next;
+}
+async function reapStaleDownloadStagingDirectories(managedDirectory, path, nowMillis) {
+	const { readdir, realpath, rm } = await import("node:fs/promises");
+	let entries;
+	try {
+		entries = await readdir(managedDirectory, { withFileTypes: true });
+	} catch (err) {
+		if (require_path_safety.hasErrorCode(err, "ENOENT")) return;
+		emitCleanupWarning("failed to inspect B2 SDK download staging entries");
+		return;
+	}
+	const cleanupErrors = [];
+	await forEachWithConcurrency(entries, MAX_STAGING_CLEANUP_CONCURRENCY, async (entry) => {
+		if (!entry.isDirectory() || !entry.name.endsWith(DOWNLOAD_STAGING_ENTRY_SUFFIX)) return;
+		const candidate = path.join(managedDirectory, entry.name);
+		const activity = await readManagedStagingEntryActivity(candidate, path);
+		if (activity === void 0 || !stagingActivityIsStale(activity, nowMillis)) return;
+		const realCandidate = await realpath(candidate).catch(() => {
+			cleanupErrors.push({
+				entryName: entry.name,
+				operation: "inspect"
+			});
+		});
+		if (realCandidate === void 0) return;
+		try {
+			require_path_safety.assertPathInsideRoot(managedDirectory, realCandidate, path);
+			const latestActivity = await readManagedStagingEntryActivity(candidate, path);
+			if (latestActivity === void 0 || latestActivity.signature !== activity.signature || !stagingActivityIsStale(latestActivity, nowMillis)) return;
+			await rm(realCandidate, {
+				recursive: true,
+				force: true
+			});
+		} catch {
+			cleanupErrors.push({
+				entryName: entry.name,
+				operation: "remove"
+			});
+		}
+	});
+	if (cleanupErrors.length > 0) {
+		const noun = cleanupErrors.length === 1 ? "entry" : "entries";
+		emitCleanupWarning(`failed to reap ${cleanupErrors.length} stale B2 SDK download staging ${noun}: ${cleanupErrors.slice(0, MAX_CLEANUP_WARNING_ENTRIES).map(formatCleanupWarning).join("; ")}`);
+	}
+}
+async function readManagedStagingEntryActivity(candidate, path) {
+	const { lstat, readdir } = await import("node:fs/promises");
+	try {
+		const [directoryStats, markerStats] = await Promise.all([lstat(candidate), lstat(path.join(candidate, DOWNLOAD_STAGING_MARKER_NAME))]);
+		if (!directoryStats.isDirectory() || !markerStats.isFile()) return void 0;
+		const entries = await readdir(candidate, { withFileTypes: true });
+		if (entries.length > 1024) return void 0;
+		const statsParts = [`.:${stagingStatsSignature(directoryStats)}`, `${DOWNLOAD_STAGING_MARKER_NAME}:${stagingStatsSignature(markerStats)}`];
+		let newestActivityMs = Math.max(stagingStatsActivityMs(directoryStats), stagingStatsActivityMs(markerStats));
+		for (const entry of [...entries].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+			const stats = await lstat(path.join(candidate, entry.name));
+			statsParts.push(`${entry.name}:${stagingStatsSignature(stats)}`);
+			newestActivityMs = Math.max(newestActivityMs, stagingStatsActivityMs(stats));
+		}
+		return {
+			newestActivityMs,
+			signature: statsParts.join("|")
+		};
+	} catch {
+		return;
+	}
+}
+function stagingStatsActivityMs(stats) {
+	return stats.mtimeMs;
+}
+function stagingStatsSignature(stats) {
+	return `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeMs}:${stats.ctimeMs}`;
+}
+function stagingActivityIsStale(activity, nowMillis) {
+	return nowMillis - activity.newestActivityMs >= STALE_DOWNLOAD_STAGING_AGE_MS;
+}
+function formatCleanupWarning(error) {
+	return `${error.operation} ${safeWarningName(error.entryName)}`;
+}
+function safeWarningName(name) {
+	const chars = Array.from(name);
+	const bounded = chars.slice(0, 80).join("");
+	const suffix = chars.length > 80 ? "..." : "";
+	return JSON.stringify(`${bounded.replace(/[^A-Za-z0-9._-]/g, "?")}${suffix}`);
+}
+function canonicalLocalFilesystemSegment(segment) {
+	return segment.normalize("NFC").toLocaleLowerCase("en-US");
+}
+async function forEachWithConcurrency(items, concurrency, fn) {
+	let index = 0;
+	const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+		while (index < items.length) {
+			const item = items[index];
+			index += 1;
+			if (item !== void 0) await fn(item);
+		}
+	});
+	await Promise.all(workers);
+}
+function emitCleanupWarning(message) {
+	globalThis.process?.emitWarning?.(message, { code: "B2SDK_DOWNLOAD_STAGING_CLEANUP_FAILED" });
+}
+//#endregion
+exports.DOWNLOAD_STAGING_ACTIVITY_ENTRY_LIMIT = DOWNLOAD_STAGING_ACTIVITY_ENTRY_LIMIT;
+exports.DOWNLOAD_STAGING_DIRECTORY_NAME = DOWNLOAD_STAGING_DIRECTORY_NAME;
+exports.DOWNLOAD_STAGING_MARKER_NAME = DOWNLOAD_STAGING_MARKER_NAME;
+exports.assertDownloadPathSameDevice = assertDownloadPathSameDevice;
+exports.createDownloadStagingDirectory = createDownloadStagingDirectory;
+exports.isDownloadStagingDirectorySegment = isDownloadStagingDirectorySegment;
+exports.isManagedDownloadStagingRoot = isManagedDownloadStagingRoot;
+
+//# sourceMappingURL=download-staging.cjs.map

package/dist/sync/download-staging.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"download-staging.cjs","names":[],"sources":["../../src/sync/download-staging.ts"],"sourcesContent":["import { assertPathInsideRoot, hasErrorCode, noFollowFlag } from './path-safety.ts'\n\ntype DeviceStat = { readonly dev: number | bigint }\ntype DeviceStatFn = (path: string) => Promise<DeviceStat>\n\n/** @internal */\nexport const DOWNLOAD_STAGING_DIRECTORY_NAME = '.b2sdk-download-staging'\n/** @internal */\nexport const DOWNLOAD_STAGING_MARKER_NAME = '.b2sdk-staging-marker.partial'\n\nconst CANONICAL_DOWNLOAD_STAGING_DIRECTORY_NAME = canonicalLocalFilesystemSegment(\n  DOWNLOAD_STAGING_DIRECTORY_NAME,\n)\nconst DOWNLOAD_STAGING_ENTRY_SUFFIX = '.download'\nconst STALE_DOWNLOAD_STAGING_AGE_MS = 24 * 60 * 60 * 1000\nconst MAX_STAGING_CLEANUP_CONCURRENCY = 8\nconst MAX_CLEANUP_WARNING_ENTRIES = 3\n/** @internal */\nexport const DOWNLOAD_STAGING_ACTIVITY_ENTRY_LIMIT = 1024\nconst reapedManagedDirectories = new Map<string, Promise<void>>()\n\ntype StagingActivitySnapshot = {\n  readonly newestActivityMs: number\n  readonly signature: string\n}\n\ntype CleanupWarning = {\n  readonly entryName: string\n  readonly operation: 'inspect' | 'remove'\n}\n\n/**\n * Checks whether a single path segment matches the SDK-managed staging directory name.\n * @param segment - Candidate path segment.\n *\n * @returns True when the segment is the reserved staging directory name under\n * local filesystem canonicalization.\n *\n * @internal\n */\nexport function isDownloadStagingDirectorySegment(segment: string | undefined): boolean {\n  return (\n    segment !== undefined &&\n    canonicalLocalFilesystemSegment(segment) === CANONICAL_DOWNLOAD_STAGING_DIRECTORY_NAME\n  )\n}\n\n/**\n * Creates a private SDK-managed staging directory under a local sync root.\n * @param rootRealPath - Resolved local sync root path.\n * @param path - Node path module used for platform-specific path operations.\n * @param randomUUID - UUID provider used to create unique staging entries.\n * @param statForDeviceCheck - Stat function used to verify filesystem devices.\n * @param beforeStagingMarkerWrite - Test hook called before marker creation.\n *\n * @returns The resolved staging directory path.\n *\n * @internal\n */\nexport async function createDownloadStagingDirectory(\n  rootRealPath: string,\n  path: typeof import('node:path'),\n  randomUUID: () => string,\n  statForDeviceCheck: DeviceStatFn,\n  beforeStagingMarkerWrite?: (directory: string) => Promise<void> | void,\n): Promise<string> {\n  const { chmod, lstat, mkdir, readdir, realpath, rm } = await import('node:fs/promises')\n  const managedDirectory = path.join(rootRealPath, DOWNLOAD_STAGING_DIRECTORY_NAME)\n  try {\n    await mkdir(managedDirectory, { mode: PRIVATE_DOWNLOAD_DIRECTORY_MODE })\n  } catch (err) {\n    if (!hasErrorCode(err, 'EEXIST')) throw err\n  }\n  const managedStats = await lstat(managedDirectory)\n  if (!managedStats.isDirectory()) {\n    throw new Error(\n      `unsafe local destination path: ${DOWNLOAD_STAGING_DIRECTORY_NAME} is not a directory`,\n    )\n  }\n  const realManagedDirectory = await realpath(managedDirectory)\n  assertPathInsideRoot(rootRealPath, realManagedDirectory, path)\n  await assertDownloadPathSameDevice(\n    rootRealPath,\n    realManagedDirectory,\n    statForDeviceCheck,\n    'unsafe local destination path: cannot stage download across filesystems',\n  )\n\n  if (!(await isManagedDownloadStagingRoot(realManagedDirectory))) {\n    const entries = await readdir(realManagedDirectory)\n    if (entries.length > 0 && !(await isManagedDownloadStagingRoot(realManagedDirectory))) {\n      throw new Error(\n        `unsafe local destination path: ${DOWNLOAD_STAGING_DIRECTORY_NAME} is reserved for SDK download staging`,\n      )\n    }\n  }\n  await beforeStagingMarkerWrite?.(realManagedDirectory)\n  await writeStagingMarker(realManagedDirectory, path)\n  /* v8 ignore next -- best-effort chmod */\n  await chmod(realManagedDirectory, PRIVATE_DOWNLOAD_DIRECTORY_MODE).catch(() => {})\n  await reapStaleDownloadStagingDirectoriesOnce(realManagedDirectory, path, Date.now())\n\n  const stagingDirectory = path.join(\n    realManagedDirectory,\n    `${Date.now()}-${randomUUID()}${DOWNLOAD_STAGING_ENTRY_SUFFIX}`,\n  )\n  await mkdir(stagingDirectory, { mode: PRIVATE_DOWNLOAD_DIRECTORY_MODE })\n  /* v8 ignore next -- best-effort chmod */\n  await chmod(stagingDirectory, PRIVATE_DOWNLOAD_DIRECTORY_MODE).catch(() => {})\n  try {\n    const realStagingDirectory = await realpath(stagingDirectory)\n    assertPathInsideRoot(realManagedDirectory, realStagingDirectory, path)\n    await assertDownloadPathSameDevice(\n      rootRealPath,\n      realStagingDirectory,\n      statForDeviceCheck,\n      'unsafe local destination path: cannot stage download across filesystems',\n    )\n    await beforeStagingMarkerWrite?.(realStagingDirectory)\n    await writeStagingMarker(realStagingDirectory, path)\n    return realStagingDirectory\n  } catch (err) {\n    /* v8 ignore next -- best-effort cleanup */\n    await rm(stagingDirectory, { recursive: true, force: true }).catch(() => {})\n    throw err\n  }\n}\n\n/**\n * Returns true when a scan-root entry is an SDK-managed download staging root.\n * @param directory - Candidate directory to inspect.\n *\n * @returns True when the directory contains SDK staging markers.\n *\n * @internal\n */\nexport async function isManagedDownloadStagingRoot(directory: string): Promise<boolean> {\n  const { lstat, readdir } = await import('node:fs/promises')\n  const path = await import('node:path')\n\n  try {\n    const markerStats = await lstat(path.join(directory, DOWNLOAD_STAGING_MARKER_NAME))\n    if (markerStats.isFile()) return true\n  } catch (err) {\n    if (!hasErrorCode(err, 'ENOENT')) return false\n  }\n\n  let entries: import('node:fs').Dirent[]\n  try {\n    entries = await readdir(directory, { withFileTypes: true })\n  } catch {\n    return false\n  }\n\n  for (const entry of entries) {\n    if (!entry.isDirectory() || !entry.name.endsWith(DOWNLOAD_STAGING_ENTRY_SUFFIX)) continue\n    try {\n      const markerStats = await lstat(\n        path.join(directory, entry.name, DOWNLOAD_STAGING_MARKER_NAME),\n      )\n      if (markerStats.isFile()) return true\n    } catch {\n      // Keep checking siblings; one corrupt entry should not hide user content.\n    }\n  }\n  return false\n}\n\nconst PRIVATE_DOWNLOAD_FILE_MODE = 0o600\nconst PRIVATE_DOWNLOAD_DIRECTORY_MODE = 0o700\n\nasync function writeStagingMarker(\n  directory: string,\n  path: typeof import('node:path'),\n): Promise<void> {\n  const { constants } = await import('node:fs')\n  const { lstat, open } = await import('node:fs/promises')\n  const markerPath = path.join(directory, DOWNLOAD_STAGING_MARKER_NAME)\n  let handle: Awaited<ReturnType<typeof open>> | undefined\n  try {\n    handle = await open(\n      markerPath,\n      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollowFlag(constants),\n      PRIVATE_DOWNLOAD_FILE_MODE,\n    )\n    /* v8 ignore next -- best-effort chmod */\n    await handle.chmod(PRIVATE_DOWNLOAD_FILE_MODE).catch(() => {})\n  } catch (err) {\n    if (hasErrorCode(err, 'EEXIST') || hasErrorCode(err, 'ELOOP')) {\n      const markerStats = await lstat(markerPath).catch(() => undefined)\n      if (markerStats?.isFile() === true) return\n      throw new Error('unsafe local destination path: staging marker is not a regular file')\n    }\n    throw err\n  } finally {\n    /* v8 ignore next -- best-effort close */\n    await handle?.close().catch(() => {})\n  }\n}\n\n/**\n * Verifies that a candidate path is on the same filesystem device as the root.\n * @param rootRealPath - Resolved local sync root path.\n * @param candidateRealPath - Resolved candidate path to compare.\n * @param statForDeviceCheck - Stat function used to read device IDs.\n * @param message - Error message used when devices differ.\n *\n * @internal\n */\nexport async function assertDownloadPathSameDevice(\n  rootRealPath: string,\n  candidateRealPath: string,\n  statForDeviceCheck: DeviceStatFn,\n  message: string,\n): Promise<void> {\n  const [rootStats, candidateStats] = await Promise.all([\n    statForDeviceCheck(rootRealPath),\n    statForDeviceCheck(candidateRealPath),\n  ])\n  if (rootStats.dev !== candidateStats.dev) throw new Error(message)\n}\n\nasync function reapStaleDownloadStagingDirectoriesOnce(\n  managedDirectory: string,\n  path: typeof import('node:path'),\n  nowMillis: number,\n): Promise<void> {\n  const previous = reapedManagedDirectories.get(managedDirectory)\n  if (previous !== undefined) {\n    await previous\n    return\n  }\n\n  const next = reapStaleDownloadStagingDirectories(managedDirectory, path, nowMillis).finally(\n    () => {\n      if (reapedManagedDirectories.get(managedDirectory) === next) {\n        reapedManagedDirectories.delete(managedDirectory)\n      }\n    },\n  )\n  reapedManagedDirectories.set(managedDirectory, next)\n  await next\n}\n\nasync function reapStaleDownloadStagingDirectories(\n  managedDirectory: string,\n  path: typeof import('node:path'),\n  nowMillis: number,\n): Promise<void> {\n  const { readdir, realpath, rm } = await import('node:fs/promises')\n  let entries: import('node:fs').Dirent[]\n  try {\n    entries = await readdir(managedDirectory, { withFileTypes: true })\n  } catch (err) {\n    if (hasErrorCode(err, 'ENOENT')) return\n    emitCleanupWarning('failed to inspect B2 SDK download staging entries')\n    return\n  }\n\n  const cleanupErrors: CleanupWarning[] = []\n  await forEachWithConcurrency(entries, MAX_STAGING_CLEANUP_CONCURRENCY, async (entry) => {\n    if (!entry.isDirectory() || !entry.name.endsWith(DOWNLOAD_STAGING_ENTRY_SUFFIX)) return\n    const candidate = path.join(managedDirectory, entry.name)\n    const activity = await readManagedStagingEntryActivity(candidate, path)\n    if (activity === undefined || !stagingActivityIsStale(activity, nowMillis)) return\n    const realCandidate = await realpath(candidate).catch(() => {\n      cleanupErrors.push({ entryName: entry.name, operation: 'inspect' })\n      return undefined\n    })\n    if (realCandidate === undefined) return\n    try {\n      assertPathInsideRoot(managedDirectory, realCandidate, path)\n      const latestActivity = await readManagedStagingEntryActivity(candidate, path)\n      if (\n        latestActivity === undefined ||\n        latestActivity.signature !== activity.signature ||\n        !stagingActivityIsStale(latestActivity, nowMillis)\n      ) {\n        return\n      }\n      await rm(realCandidate, { recursive: true, force: true })\n    } catch {\n      cleanupErrors.push({ entryName: entry.name, operation: 'remove' })\n    }\n  })\n\n  if (cleanupErrors.length > 0) {\n    const noun = cleanupErrors.length === 1 ? 'entry' : 'entries'\n    emitCleanupWarning(\n      `failed to reap ${cleanupErrors.length} stale B2 SDK download staging ${noun}: ${cleanupErrors\n        .slice(0, MAX_CLEANUP_WARNING_ENTRIES)\n        .map(formatCleanupWarning)\n        .join('; ')}`,\n    )\n  }\n}\n\nasync function readManagedStagingEntryActivity(\n  candidate: string,\n  path: typeof import('node:path'),\n): Promise<StagingActivitySnapshot | undefined> {\n  const { lstat, readdir } = await import('node:fs/promises')\n\n  try {\n    const [directoryStats, markerStats] = await Promise.all([\n      lstat(candidate),\n      lstat(path.join(candidate, DOWNLOAD_STAGING_MARKER_NAME)),\n    ])\n    if (!directoryStats.isDirectory() || !markerStats.isFile()) return undefined\n\n    const entries = await readdir(candidate, { withFileTypes: true })\n    if (entries.length > DOWNLOAD_STAGING_ACTIVITY_ENTRY_LIMIT) return undefined\n\n    const statsParts = [\n      `.:${stagingStatsSignature(directoryStats)}`,\n      `${DOWNLOAD_STAGING_MARKER_NAME}:${stagingStatsSignature(markerStats)}`,\n    ]\n    let newestActivityMs = Math.max(\n      stagingStatsActivityMs(directoryStats),\n      stagingStatsActivityMs(markerStats),\n    )\n\n    for (const entry of [...entries].sort((a, b) =>\n      a.name < b.name ? -1 : a.name > b.name ? 1 : 0,\n    )) {\n      const stats = await lstat(path.join(candidate, entry.name))\n      statsParts.push(`${entry.name}:${stagingStatsSignature(stats)}`)\n      newestActivityMs = Math.max(newestActivityMs, stagingStatsActivityMs(stats))\n    }\n\n    return { newestActivityMs, signature: statsParts.join('|') }\n  } catch {\n    return undefined\n  }\n}\n\nfunction stagingStatsActivityMs(stats: { readonly mtimeMs: number }) {\n  return stats.mtimeMs\n}\n\nfunction stagingStatsSignature(stats: {\n  readonly ctimeMs: number\n  readonly dev: number | bigint\n  readonly ino: number | bigint\n  readonly mtimeMs: number\n  readonly size: number\n}): string {\n  return `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeMs}:${stats.ctimeMs}`\n}\n\nfunction stagingActivityIsStale(activity: StagingActivitySnapshot, nowMillis: number): boolean {\n  return nowMillis - activity.newestActivityMs >= STALE_DOWNLOAD_STAGING_AGE_MS\n}\n\nfunction formatCleanupWarning(error: CleanupWarning): string {\n  return `${error.operation} ${safeWarningName(error.entryName)}`\n}\n\nfunction safeWarningName(name: string): string {\n  const chars = Array.from(name)\n  const bounded = chars.slice(0, 80).join('')\n  const suffix = chars.length > 80 ? '...' : ''\n  return JSON.stringify(`${bounded.replace(/[^A-Za-z0-9._-]/g, '?')}${suffix}`)\n}\n\nfunction canonicalLocalFilesystemSegment(segment: string): string {\n  return segment.normalize('NFC').toLocaleLowerCase('en-US')\n}\n\nasync function forEachWithConcurrency<T>(\n  items: readonly T[],\n  concurrency: number,\n  fn: (item: T) => Promise<void>,\n): Promise<void> {\n  let index = 0\n  const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {\n    while (index < items.length) {\n      const item = items[index]\n      index += 1\n      if (item !== undefined) await fn(item)\n    }\n  })\n  await Promise.all(workers)\n}\n\nfunction emitCleanupWarning(message: string): void {\n  const processLike = (\n    globalThis as {\n      process?: {\n        emitWarning?: (warning: string, options?: { readonly code?: string }) => void\n      }\n    }\n  ).process\n  processLike?.emitWarning?.(message, { code: 'B2SDK_DOWNLOAD_STAGING_CLEANUP_FAILED' })\n}\n"],"mappings":"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"}

package/dist/sync/download-staging.d.cts

@@ -0,0 +1,54 @@
+type DeviceStat = {
+    readonly dev: number | bigint;
+};
+type DeviceStatFn = (path: string) => Promise<DeviceStat>;
+/** @internal */
+export declare const DOWNLOAD_STAGING_DIRECTORY_NAME = ".b2sdk-download-staging";
+/** @internal */
+export declare const DOWNLOAD_STAGING_MARKER_NAME = ".b2sdk-staging-marker.partial";
+/** @internal */
+export declare const DOWNLOAD_STAGING_ACTIVITY_ENTRY_LIMIT = 1024;
+/**
+ * Checks whether a single path segment matches the SDK-managed staging directory name.
+ * @param segment - Candidate path segment.
+ *
+ * @returns True when the segment is the reserved staging directory name under
+ * local filesystem canonicalization.
+ *
+ * @internal
+ */
+export declare function isDownloadStagingDirectorySegment(segment: string | undefined): boolean;
+/**
+ * Creates a private SDK-managed staging directory under a local sync root.
+ * @param rootRealPath - Resolved local sync root path.
+ * @param path - Node path module used for platform-specific path operations.
+ * @param randomUUID - UUID provider used to create unique staging entries.
+ * @param statForDeviceCheck - Stat function used to verify filesystem devices.
+ * @param beforeStagingMarkerWrite - Test hook called before marker creation.
+ *
+ * @returns The resolved staging directory path.
+ *
+ * @internal
+ */
+export declare function createDownloadStagingDirectory(rootRealPath: string, path: typeof import('node:path'), randomUUID: () => string, statForDeviceCheck: DeviceStatFn, beforeStagingMarkerWrite?: (directory: string) => Promise<void> | void): Promise<string>;
+/**
+ * Returns true when a scan-root entry is an SDK-managed download staging root.
+ * @param directory - Candidate directory to inspect.
+ *
+ * @returns True when the directory contains SDK staging markers.
+ *
+ * @internal
+ */
+export declare function isManagedDownloadStagingRoot(directory: string): Promise<boolean>;
+/**
+ * Verifies that a candidate path is on the same filesystem device as the root.
+ * @param rootRealPath - Resolved local sync root path.
+ * @param candidateRealPath - Resolved candidate path to compare.
+ * @param statForDeviceCheck - Stat function used to read device IDs.
+ * @param message - Error message used when devices differ.
+ *
+ * @internal
+ */
+export declare function assertDownloadPathSameDevice(rootRealPath: string, candidateRealPath: string, statForDeviceCheck: DeviceStatFn, message: string): Promise<void>;
+export {};
+//# sourceMappingURL=download-staging.d.ts.map