@zero-transfer/dropbox 0.4.6 → 0.4.8

package/README.md

@@ -8,8 +8,6 @@
 npm install @zero-transfer/dropbox
 ```
 
-Installing this package automatically pulls in [`@zero-transfer/core`](https://www.npmjs.com/package/@zero-transfer/core) as a transitive dependency. The full core surface (`createTransferClient`, `uploadFile`, `downloadFile`, profiles, errors, sync planner, …) is re-exported from this package, so a single `import { … } from "@zero-transfer/dropbox"` is all you need. If your app uses multiple protocols, install the umbrella [`@zero-transfer/sdk`](https://www.npmjs.com/package/@zero-transfer/sdk) instead of multiple scoped packages.
-
 ## Overview
 
 Dropbox provider - RPC + content-host APIs, list-folder cursor pagination, ranged downloads, single-shot uploads in `overwrite` mode, and `content_hash` exposed as both `uniqueId` and `checksum`.

package/dist/index.cjs

@@ -60,6 +60,7 @@ __export(dropbox_exports, {
   copyBetween: () => copyBetween,
   createAtomicDeployPlan: () => createAtomicDeployPlan,
   createBandwidthThrottle: () => createBandwidthThrottle,
+  createDefaultRetryPolicy: () => createDefaultRetryPolicy,
   createDropboxProviderFactory: () => createDropboxProviderFactory,
   createLocalProviderFactory: () => createLocalProviderFactory,
   createMemoryProviderFactory: () => createMemoryProviderFactory,
@@ -96,8 +97,10 @@ __export(dropbox_exports, {
   parseRemoteManifest: () => parseRemoteManifest,
   redactCommand: () => redactCommand,
   redactConnectionProfile: () => redactConnectionProfile,
+  redactErrorForLogging: () => redactErrorForLogging,
   redactObject: () => redactObject,
   redactSecretSource: () => redactSecretSource,
+  redactUrlForLogging: () => redactUrlForLogging,
   redactValue: () => redactValue,
   resolveConnectionProfileSecrets: () => resolveConnectionProfileSecrets,
   resolveOpenSshHost: () => resolveOpenSshHost,
@@ -118,6 +121,68 @@ module.exports = __toCommonJS(dropbox_exports);
 // src/client/ZeroTransfer.ts
 var import_node_events = require("events");
 
+// src/logging/redaction.ts
+var REDACTED = "[REDACTED]";
+var SENSITIVE_KEY_PATTERN = /(?:password|passphrase|privatekey|token|secret|username|user)$/i;
+var SECRET_COMMAND_PATTERN = /^(PASS|USER|ACCT)\s+(.+)$/i;
+var URL_KEY_PATTERN = /(?:url|uri|href)$/i;
+function isSensitiveKey(key) {
+  return SENSITIVE_KEY_PATTERN.test(key.replace(/[_-]/g, ""));
+}
+function redactCommand(command) {
+  return command.replace(SECRET_COMMAND_PATTERN, (_fullMatch, commandName) => {
+    return `${commandName.toUpperCase()} ${REDACTED}`;
+  });
+}
+function redactValue(value) {
+  if (typeof value === "string") {
+    return redactCommand(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redactValue(item));
+  }
+  if (value !== null && typeof value === "object") {
+    return redactObject(value);
+  }
+  return value;
+}
+function redactObject(input) {
+  return Object.fromEntries(
+    Object.entries(input).map(([key, value]) => {
+      if (isSensitiveKey(key)) {
+        return [key, REDACTED];
+      }
+      if (URL_KEY_PATTERN.test(key) && typeof value === "string") {
+        return [key, redactUrlForLogging(value)];
+      }
+      return [key, redactValue(value)];
+    })
+  );
+}
+function redactUrlForLogging(url) {
+  let parsed;
+  try {
+    parsed = typeof url === "string" ? new URL(url) : url;
+  } catch {
+    return REDACTED;
+  }
+  const origin = parsed.host.length > 0 ? `${parsed.protocol}//${parsed.host}` : parsed.protocol;
+  const query = parsed.search.length > 0 ? `?${REDACTED}` : "";
+  return `${origin}${parsed.pathname}${query}`;
+}
+function redactErrorForLogging(error) {
+  if (error !== null && typeof error === "object") {
+    const candidate = error;
+    if (typeof candidate.toJSON === "function") {
+      return redactObject(candidate.toJSON());
+    }
+  }
+  if (error instanceof Error) {
+    return redactObject({ message: error.message, name: error.name });
+  }
+  return { message: redactValue(typeof error === "string" ? error : String(error)) };
+}
+
 // src/errors/ZeroTransferError.ts
 var ZeroTransferError = class extends Error {
   /** Stable machine-readable error code. */
@@ -159,6 +224,11 @@ var ZeroTransferError = class extends Error {
   /**
    * Serializes the error into a plain object suitable for logs or API responses.
    *
+   * `details` and `command` are passed through secret redaction so serialized
+   * errors never leak credentials, signed URLs, or raw protocol commands. The
+   * live {@link ZeroTransferError.details | details} property stays unredacted
+   * for programmatic consumers.
+   *
    * @returns A JSON-safe object containing public structured error fields.
    */
   toJSON() {
@@ -168,12 +238,12 @@ var ZeroTransferError = class extends Error {
       message: this.message,
       protocol: this.protocol,
       host: this.host,
-      command: this.command,
+      command: this.command === void 0 ? void 0 : redactCommand(this.command),
       ftpCode: this.ftpCode,
       sftpCode: this.sftpCode,
       path: this.path,
       retryable: this.retryable,
-      details: this.details
+      details: this.details === void 0 ? void 0 : redactObject(this.details)
     };
   }
 };
@@ -696,15 +766,20 @@ var ProviderRegistry = class {
 var TransferClient = class {
   /** Provider registry used by this client. */
   registry;
+  /** Execution defaults applied when call sites omit their own values. */
+  defaults;
   logger;
   /**
    * Creates a transfer client without opening any provider connections.
    *
-   * @param options - Optional registry, provider factories, and logger.
+   * @param options - Optional registry, provider factories, logger, and execution defaults.
    */
   constructor(options = {}) {
     this.registry = options.registry ?? new ProviderRegistry();
     this.logger = options.logger ?? noopLogger;
+    if (options.defaults !== void 0) {
+      this.defaults = { ...options.defaults };
+    }
     for (const provider of options.providers ?? []) {
       this.registry.register(provider);
     }
@@ -1277,18 +1352,25 @@ var TransferEngine = class {
       for (let attemptNumber = 1; attemptNumber <= maxAttempts; attemptNumber += 1) {
         this.throwIfAborted(abortScope.signal, job);
         const attemptStartedAt = this.now();
+        const attemptScope = createAttemptScope(
+          abortScope.signal,
+          options.timeout,
+          job,
+          attemptNumber
+        );
         const context = this.createExecutionContext(
           job,
           attemptNumber,
           attemptStartedAt,
           options,
-          abortScope.signal,
+          attemptScope.signal,
           (bytesTransferred) => {
             latestBytesTransferred = bytesTransferred;
-          }
+          },
+          attemptScope.notifyProgress
         );
         try {
-          const result = await runExecutor(executor, context, abortScope.signal, job);
+          const result = await runExecutor(executor, context, attemptScope.signal, job);
           context.throwIfAborted();
           latestBytesTransferred = result.bytesTransferred;
           const completedAt = this.now();
@@ -1306,16 +1388,27 @@ var TransferEngine = class {
             summarizeError(error)
           );
           attempts.push(attempt);
-          if (error instanceof AbortError || error instanceof TimeoutError) {
+          if (error instanceof AbortError || abortScope.signal?.aborted === true) {
             throw error;
           }
-          const retryInput = { attempt: attemptNumber, error, job };
+          const retryInput = {
+            attempt: attemptNumber,
+            elapsedMs: Math.max(0, completedAt.getTime() - startedAt.getTime()),
+            error,
+            job
+          };
           const shouldRetry = attemptNumber < maxAttempts && (options.retry?.shouldRetry?.(retryInput) ?? isRetryable(error));
           if (shouldRetry) {
             options.retry?.onRetry?.(retryInput);
+            const delayMs = normalizeDelayMs(options.retry?.getDelayMs?.(retryInput));
+            if (delayMs > 0) {
+              await sleepWithAbort(delayMs, abortScope.signal, job);
+            }
             continue;
           }
           throw createTransferFailure(job, error, attempts);
+        } finally {
+          attemptScope.dispose();
         }
       }
       throw createTransferFailure(job, void 0, attempts);
@@ -1323,12 +1416,13 @@ var TransferEngine = class {
       abortScope.dispose();
     }
   }
-  createExecutionContext(job, attempt, startedAt, options, signal, updateBytesTransferred) {
+  createExecutionContext(job, attempt, startedAt, options, signal, updateBytesTransferred, notifyProgress) {
     const context = {
       attempt,
       job,
       reportProgress: (bytesTransferred, totalBytes) => {
         this.throwIfAborted(signal, job);
+        notifyProgress();
         updateBytesTransferred(bytesTransferred);
         const progressInput = {
           bytesTransferred,
@@ -1397,6 +1491,96 @@ function createAbortScope(parentSignal, timeout, job) {
     signal: controller.signal
   };
 }
+function createAttemptScope(parentSignal, timeout, job, attempt) {
+  const attemptTimeoutMs = normalizeTimeoutMs(timeout?.attemptTimeoutMs);
+  const stallTimeoutMs = normalizeTimeoutMs(timeout?.stallTimeoutMs);
+  if (attemptTimeoutMs === void 0 && stallTimeoutMs === void 0) {
+    const scope = {
+      dispose: () => void 0,
+      notifyProgress: () => void 0
+    };
+    if (parentSignal !== void 0) scope.signal = parentSignal;
+    return scope;
+  }
+  const controller = new AbortController();
+  const retryable = timeout?.retryable ?? true;
+  const abortFromParent = () => controller.abort(parentSignal?.reason);
+  if (parentSignal?.aborted === true) {
+    abortFromParent();
+  } else {
+    parentSignal?.addEventListener("abort", abortFromParent, { once: true });
+  }
+  const attemptTimer = attemptTimeoutMs === void 0 ? void 0 : setTimeout(() => {
+    controller.abort(
+      new TimeoutError({
+        details: { attempt, attemptTimeoutMs, jobId: job.id, operation: job.operation },
+        message: `Transfer attempt ${String(attempt)} timed out after ${String(attemptTimeoutMs)}ms: ${job.id}`,
+        retryable
+      })
+    );
+  }, attemptTimeoutMs);
+  let stallTimer;
+  const armStallWatchdog = () => {
+    if (stallTimeoutMs === void 0 || controller.signal.aborted) return;
+    if (stallTimer !== void 0) clearTimeout(stallTimer);
+    stallTimer = setTimeout(() => {
+      controller.abort(
+        new TimeoutError({
+          details: { attempt, jobId: job.id, operation: job.operation, stallTimeoutMs },
+          message: `Transfer attempt ${String(attempt)} stalled (no progress for ${String(stallTimeoutMs)}ms): ${job.id}`,
+          retryable
+        })
+      );
+    }, stallTimeoutMs);
+  };
+  armStallWatchdog();
+  return {
+    dispose: () => {
+      if (attemptTimer !== void 0) clearTimeout(attemptTimer);
+      if (stallTimer !== void 0) clearTimeout(stallTimer);
+      parentSignal?.removeEventListener("abort", abortFromParent);
+    },
+    notifyProgress: armStallWatchdog,
+    signal: controller.signal
+  };
+}
+function sleepWithAbort(delayMs, signal, job) {
+  return new Promise((resolve, reject) => {
+    if (signal === void 0) {
+      setTimeout(resolve, delayMs);
+      return;
+    }
+    if (signal.aborted) {
+      reject(toAbortFailure(signal, job));
+      return;
+    }
+    const rejectAbort = () => {
+      clearTimeout(timer);
+      reject(toAbortFailure(signal, job));
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", rejectAbort);
+      resolve();
+    }, delayMs);
+    signal.addEventListener("abort", rejectAbort, { once: true });
+  });
+}
+function toAbortFailure(signal, job) {
+  if (signal.reason instanceof ZeroTransferError) {
+    return signal.reason;
+  }
+  return new AbortError({
+    details: { jobId: job.id, operation: job.operation },
+    message: `Transfer job aborted: ${job.id}`,
+    retryable: false
+  });
+}
+function normalizeDelayMs(value) {
+  if (value === void 0 || !Number.isFinite(value) || value <= 0) {
+    return 0;
+  }
+  return Math.floor(value);
+}
 function normalizeTimeoutMs(value) {
   if (value === void 0 || !Number.isFinite(value) || value <= 0) {
     return void 0;
@@ -1565,7 +1749,7 @@ async function runRoute(options) {
     const executor = createProviderTransferExecutor({
       resolveSession: ({ role }) => sessions.get(role)
     });
-    return await engine.execute(job, executor, buildExecuteOptions(options));
+    return await engine.execute(job, executor, buildExecuteOptions(options, client));
   } finally {
     if (destinationSession !== void 0) {
       await destinationSession.disconnect();
@@ -1602,12 +1786,14 @@ function defaultJobId(route, now) {
   const timestamp = (now?.() ?? /* @__PURE__ */ new Date()).getTime();
   return `route:${route.id}:${timestamp.toString(36)}`;
 }
-function buildExecuteOptions(options) {
+function buildExecuteOptions(options, client) {
   const execute = {};
+  const retry = options.retry ?? client.defaults?.retry;
+  const timeout = options.timeout ?? client.defaults?.timeout;
   if (options.signal !== void 0) execute.signal = options.signal;
-  if (options.retry !== void 0) execute.retry = options.retry;
+  if (retry !== void 0) execute.retry = retry;
   if (options.onProgress !== void 0) execute.onProgress = options.onProgress;
-  if (options.timeout !== void 0) execute.timeout = options.timeout;
+  if (timeout !== void 0) execute.timeout = timeout;
   if (options.bandwidthLimit !== void 0) execute.bandwidthLimit = options.bandwidthLimit;
   return execute;
 }
@@ -1664,41 +1850,6 @@ function defaultRouteSuffix(source, destination) {
   return `${source}->${destination}`;
 }
 
-// src/logging/redaction.ts
-var REDACTED = "[REDACTED]";
-var SENSITIVE_KEY_PATTERN = /(?:password|passphrase|privatekey|token|secret|username|user)$/i;
-var SECRET_COMMAND_PATTERN = /^(PASS|USER|ACCT)\s+(.+)$/i;
-function isSensitiveKey(key) {
-  return SENSITIVE_KEY_PATTERN.test(key.replace(/[_-]/g, ""));
-}
-function redactCommand(command) {
-  return command.replace(SECRET_COMMAND_PATTERN, (_fullMatch, commandName) => {
-    return `${commandName.toUpperCase()} ${REDACTED}`;
-  });
-}
-function redactValue(value) {
-  if (typeof value === "string") {
-    return redactCommand(value);
-  }
-  if (Array.isArray(value)) {
-    return value.map((item) => redactValue(item));
-  }
-  if (value !== null && typeof value === "object") {
-    return redactObject(value);
-  }
-  return value;
-}
-function redactObject(input) {
-  return Object.fromEntries(
-    Object.entries(input).map(([key, value]) => {
-      if (isSensitiveKey(key)) {
-        return [key, REDACTED];
-      }
-      return [key, redactValue(value)];
-    })
-  );
-}
-
 // src/profiles/SecretSource.ts
 var import_node_buffer2 = require("buffer");
 var import_promises = require("fs/promises");
@@ -2070,11 +2221,11 @@ var import_promises2 = require("fs/promises");
 var import_node_path2 = __toESM(require("path"));
 
 // src/utils/path.ts
-var UNSAFE_FTP_ARGUMENT_PATTERN = /[\r\n]/;
+var UNSAFE_FTP_ARGUMENT_PATTERN = /[\r\n\0]/;
 function assertSafeFtpArgument(value, label = "path") {
   if (UNSAFE_FTP_ARGUMENT_PATTERN.test(value)) {
     throw new ConfigurationError({
-      message: `Unsafe FTP ${label}: CR and LF characters are not allowed`,
+      message: `Unsafe FTP ${label}: CR, LF, and NUL characters are not allowed`,
       retryable: false,
       details: {
         label
@@ -3376,7 +3527,6 @@ function expandAlgorithms(values) {
 }
 
 // src/profiles/importers/FileZillaImporter.ts
-var import_node_buffer5 = require("buffer");
 function importFileZillaSites(xml) {
   const events = tokenizeXml(xml);
   if (events.length === 0) {
@@ -3392,7 +3542,6 @@ function importFileZillaSites(xml) {
   const folderNamePending = [];
   let inServer = false;
   let serverFields = {};
-  let serverPasswordEncoding;
   let activeTag;
   let captureFolderName = false;
   for (const event of events) {
@@ -3405,13 +3554,9 @@ function importFileZillaSites(xml) {
       if (event.name === "Server") {
         inServer = true;
         serverFields = {};
-        serverPasswordEncoding = void 0;
         continue;
       }
       activeTag = event.name;
-      if (event.name === "Pass" && inServer) {
-        serverPasswordEncoding = event.attributes["encoding"];
-      }
       if (event.name === "Name" && !inServer && folderNamePending.length > 0) {
         captureFolderName = true;
       }
@@ -3437,7 +3582,7 @@ function importFileZillaSites(xml) {
       }
       if (event.name === "Server") {
         const folder = folderStack.filter((segment) => segment !== "");
-        const result = buildSiteFromFields(serverFields, serverPasswordEncoding);
+        const result = buildSiteFromFields(serverFields);
         if (result.kind === "site") {
           sites.push({ ...result.site, folder });
         } else {
@@ -3449,7 +3594,6 @@ function importFileZillaSites(xml) {
         }
         inServer = false;
         serverFields = {};
-        serverPasswordEncoding = void 0;
         activeTag = void 0;
         continue;
       }
@@ -3458,7 +3602,7 @@ function importFileZillaSites(xml) {
   }
   return { sites, skipped };
 }
-function buildSiteFromFields(fields, passwordEncoding) {
+function buildSiteFromFields(fields) {
   const name = (fields["Name"] ?? fields["Host"] ?? "Untitled").trim();
   const host = (fields["Host"] ?? "").trim();
   if (host === "") return { kind: "skipped", name };
@@ -3477,18 +3621,9 @@ function buildSiteFromFields(fields, passwordEncoding) {
   }
   const user = fields["User"]?.trim();
   if (user !== void 0 && user !== "") profile.username = { value: user };
-  let password;
   const rawPass = fields["Pass"];
-  if (rawPass !== void 0 && rawPass !== "") {
-    if (passwordEncoding === "base64") {
-      password = import_node_buffer5.Buffer.from(rawPass, "base64").toString("utf8");
-    } else {
-      password = rawPass;
-    }
-    if (password !== void 0 && password !== "") profile.password = { value: password };
-  }
-  const site = { name, profile };
-  if (password !== void 0) site.password = password;
+  const hasStoredPassword = rawPass !== void 0 && rawPass !== "";
+  const site = { hasStoredPassword, name, profile };
   const logonText = fields["Logontype"];
   if (logonText !== void 0) {
     const logonType = Number.parseInt(logonText.trim(), 10);
@@ -3731,6 +3866,62 @@ function mapFtp550(details) {
   return new PermissionDeniedError(details);
 }
 
+// src/transfers/createDefaultRetryPolicy.ts
+var DEFAULT_MAX_ATTEMPTS = 4;
+var DEFAULT_BASE_DELAY_MS = 250;
+var DEFAULT_MAX_DELAY_MS = 3e4;
+var DEFAULT_MAX_ELAPSED_MS = 3e5;
+function createDefaultRetryPolicy(options = {}) {
+  const maxAttempts = normalizePositiveInteger(options.maxAttempts, DEFAULT_MAX_ATTEMPTS);
+  const baseDelayMs = normalizeNonNegative(options.baseDelayMs, DEFAULT_BASE_DELAY_MS);
+  const maxDelayMs = normalizeNonNegative(options.maxDelayMs, DEFAULT_MAX_DELAY_MS);
+  const maxElapsedMs = normalizeNonNegative(options.maxElapsedMs, DEFAULT_MAX_ELAPSED_MS);
+  const random = options.random ?? Math.random;
+  return {
+    getDelayMs(input) {
+      const retryAfterMs = readRetryAfterMs(input.error);
+      if (retryAfterMs !== void 0) {
+        return retryAfterMs;
+      }
+      const exponentialMs = baseDelayMs * 2 ** (input.attempt - 1);
+      const cappedMs = Math.min(maxDelayMs, exponentialMs);
+      return Math.floor(random() * cappedMs);
+    },
+    maxAttempts,
+    shouldRetry(input) {
+      if (!(input.error instanceof ZeroTransferError) || !input.error.retryable) {
+        return false;
+      }
+      if (input.elapsedMs >= maxElapsedMs) {
+        return false;
+      }
+      const retryAfterMs = readRetryAfterMs(input.error);
+      if (retryAfterMs !== void 0 && input.elapsedMs + retryAfterMs > maxElapsedMs) {
+        return false;
+      }
+      return true;
+    }
+  };
+}
+function readRetryAfterMs(error) {
+  if (!(error instanceof ZeroTransferError)) return void 0;
+  const value = error.details?.["retryAfterMs"];
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return void 0;
+  return Math.floor(value);
+}
+function normalizePositiveInteger(value, fallback) {
+  if (value === void 0 || !Number.isFinite(value) || value < 1) {
+    return fallback;
+  }
+  return Math.floor(value);
+}
+function normalizeNonNegative(value, fallback) {
+  if (value === void 0 || !Number.isFinite(value) || value < 0) {
+    return fallback;
+  }
+  return Math.floor(value);
+}
+
 // src/transfers/TransferPlan.ts
 function createTransferPlan(input) {
   const plan = {
@@ -3828,8 +4019,8 @@ var TransferQueue = class {
     this.concurrency = normalizeConcurrency(options.concurrency);
     this.defaultExecutor = options.executor;
     this.resolveExecutor = options.resolveExecutor;
-    this.retry = options.retry;
-    this.timeout = options.timeout;
+    this.retry = options.retry ?? options.client?.defaults?.retry;
+    this.timeout = options.timeout ?? options.client?.defaults?.timeout;
     this.bandwidthLimit = options.bandwidthLimit;
     this.onProgress = options.onProgress;
     this.onReceipt = options.onReceipt;
@@ -4906,7 +5097,7 @@ function isMainModule(importMetaUrl) {
 }
 
 // src/providers/web/httpInternals.ts
-var import_node_buffer6 = require("buffer");
+var import_node_buffer5 = require("buffer");
 function parseContentRangeTotal(value) {
   const match = /\/(\d+)\s*$/.exec(value);
   if (match === null) return void 0;
@@ -4936,9 +5127,19 @@ async function* webStreamToAsyncIterable(body) {
   const reader = body.getReader();
   try {
     while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      if (value !== void 0) yield value;
+      let result;
+      try {
+        result = await reader.read();
+      } catch (error) {
+        if (error instanceof ZeroTransferError) throw error;
+        throw new ConnectionError({
+          cause: error,
+          message: "HTTP response stream was interrupted before completion",
+          retryable: true
+        });
+      }
+      if (result.done) break;
+      if (result.value !== void 0) yield result.value;
     }
   } finally {
     reader.releaseLock();
@@ -4946,8 +5147,8 @@ async function* webStreamToAsyncIterable(body) {
 }
 function secretToString(value) {
   if (typeof value === "string") return value;
-  if (value instanceof Uint8Array || import_node_buffer6.Buffer.isBuffer(value)) {
-    return import_node_buffer6.Buffer.from(value).toString("utf8");
+  if (value instanceof Uint8Array || import_node_buffer5.Buffer.isBuffer(value)) {
+    return import_node_buffer5.Buffer.from(value).toString("utf8");
   }
   return String(value);
 }
@@ -5375,6 +5576,7 @@ async function collectChunks(source) {
   copyBetween,
   createAtomicDeployPlan,
   createBandwidthThrottle,
+  createDefaultRetryPolicy,
   createDropboxProviderFactory,
   createLocalProviderFactory,
   createMemoryProviderFactory,
@@ -5411,8 +5613,10 @@ async function collectChunks(source) {
   parseRemoteManifest,
   redactCommand,
   redactConnectionProfile,
+  redactErrorForLogging,
   redactObject,
   redactSecretSource,
+  redactUrlForLogging,
   redactValue,
   resolveConnectionProfileSecrets,
   resolveOpenSshHost,