@flowscripter/pluggable-io-framework 1.2.6 → 2.0.0

package/src/registry/negotiateTransfer.ts

@@ -0,0 +1,121 @@
+import {
+  BYTES_PAYLOAD_TYPE,
+  type IOProviderFactory,
+  type PayloadConverter,
+  PayloadKind,
+} from "@flowscripter/pluggable-io-framework-api";
+import { describeConverter, describeKind } from "../util/describePath.ts";
+
+/** One (factory, kind, domain) choice for one side of a transfer. */
+export interface Endpoint {
+  readonly factory: IOProviderFactory;
+  readonly kind: PayloadKind;
+  readonly domain?: string;
+}
+
+export interface Negotiation {
+  readonly source: Endpoint;
+  readonly dest: Endpoint;
+  readonly converter?: PayloadConverter;
+  readonly path: string;
+}
+
+export const DEFAULT_NATIVE_DOMAINS: readonly string[] = ["host"];
+
+/** Every (kind, domain) a factory offers, in its preference order. */
+export function endpointsOf(factory: IOProviderFactory): Endpoint[] {
+  if (factory.kind === PayloadKind.Js) {
+    return [{ factory, kind: factory.kind }];
+  }
+  return (factory.domains ?? DEFAULT_NATIVE_DOMAINS).map((domain) => ({
+    factory,
+    kind: factory.kind,
+    domain,
+  }));
+}
+
+function sharesPayloadType(source: Endpoint, dest: Endpoint): boolean {
+  const reads = source.factory.readPayloadTypes ?? [BYTES_PAYLOAD_TYPE];
+  const writes = dest.factory.writePayloadTypes ?? [BYTES_PAYLOAD_TYPE];
+  return reads.some((payloadType) => writes.includes(payloadType));
+}
+
+function matches(end: PayloadConverter["from"], endpoint: Endpoint): boolean {
+  return end.kind === endpoint.kind && (end.domain === undefined || end.domain === endpoint.domain);
+}
+
+function kindOrder(kind: PayloadKind): number {
+  return kind === PayloadKind.Js ? 0 : 1;
+}
+
+function describeSide(protocol: string, endpoints: readonly Endpoint[]): string {
+  const kinds = endpoints.map((endpoint) => describeKind(endpoint.kind, endpoint.domain));
+  return `"${protocol}" supports [${kinds.join(", ")}]`;
+}
+
+/**
+ * Chooses the (kind, domain) for each side of a transfer between factories
+ * of two protocols, considering only pairs that share an exact payload type:
+ * 1. a common (kind, domain), preferring `js`, then the source factory's
+ *    domain order;
+ * 2. otherwise the cheapest single converter from a source pair to a
+ *    destination pair;
+ * 3. otherwise an error listing what each side supports.
+ * An explicit `kind` restricts both sides to it, and allows only converters
+ * that keep it.
+ */
+export function negotiateTransfer(
+  sourceProtocol: string,
+  sourceFactories: readonly IOProviderFactory[],
+  destProtocol: string,
+  destFactories: readonly IOProviderFactory[],
+  converters: readonly PayloadConverter[],
+  kind?: PayloadKind,
+): Negotiation {
+  const restrict = (factories: readonly IOProviderFactory[]) =>
+    factories
+      .filter((factory) => kind === undefined || factory.kind === kind)
+      .flatMap(endpointsOf)
+      .sort((a, b) => kindOrder(a.kind) - kindOrder(b.kind));
+  const sources = restrict(sourceFactories);
+  const dests = restrict(destFactories);
+  const describe = (source: Endpoint, dest: Endpoint, converter?: PayloadConverter) =>
+    `${sourceProtocol}/${describeKind(source.kind, source.domain)} -> ${destProtocol}/${describeKind(dest.kind, dest.domain)}${converter ? describeConverter(converter) : ""}`;
+
+  const pairs = sources.flatMap((source) =>
+    dests.filter((dest) => sharesPayloadType(source, dest)).map((dest) => ({ source, dest })),
+  );
+  if (pairs.length === 0 && sources.length > 0 && dests.length > 0) {
+    const reads = sourceFactories.flatMap((f) => f.readPayloadTypes ?? [BYTES_PAYLOAD_TYPE]);
+    const writes = destFactories.flatMap((f) => f.writePayloadTypes ?? [BYTES_PAYLOAD_TYPE]);
+    throw new Error(
+      `No common payload type: "${sourceProtocol}" reads [${[...new Set(reads)].join(", ")}], "${destProtocol}" writes [${[...new Set(writes)].join(", ")}]`,
+    );
+  }
+
+  const common = pairs.find(
+    ({ source, dest }) => source.kind === dest.kind && source.domain === dest.domain,
+  );
+  if (common) {
+    return { ...common, path: describe(common.source, common.dest) };
+  }
+
+  const usable = converters
+    .filter(
+      (converter) =>
+        kind === undefined || (converter.from.kind === kind && converter.to.kind === kind),
+    )
+    .toSorted((a, b) => a.cost - b.cost);
+  for (const converter of usable) {
+    const pair = pairs.find(
+      ({ source, dest }) => matches(converter.from, source) && matches(converter.to, dest),
+    );
+    if (pair) {
+      return { ...pair, converter, path: describe(pair.source, pair.dest, converter) };
+    }
+  }
+
+  throw new Error(
+    `No common payload kind/domain and no registered converter between ${describeSide(sourceProtocol, sources)} and ${describeSide(destProtocol, dests)}`,
+  );
+}

package/src/retry/RetryOptions.ts

@@ -0,0 +1,26 @@
+export interface RetryOptions {
+  /**
+   * Maximum retries after a `TransientIOError`. For an unbounded source this
+   * counts consecutive failures and resets once an item arrives.
+   */
+  readonly maxRetries: number;
+  /** Delay in ms before the given retry attempt (1-based). Defaults to `min(200 * 2^attempt, 5000)`. */
+  readonly backoffMs?: (attempt: number) => number;
+  /**
+   * Unbounded sources only: what to do when the source fails and has to be
+   * reconnected, leaving a gap. Defaults to `"continue"`.
+   */
+  readonly onGap?: "continue" | "fail";
+}
+
+export const DEFAULT_RETRY: RetryOptions = { maxRetries: 3 };
+
+export function defaultBackoffMs(attempt: number): number {
+  return Math.min(200 * 2 ** attempt, 5000);
+}
+
+/** Waits for the backoff delay before retry `attempt`. */
+export function backoff(options: RetryOptions, attempt: number): Promise<void> {
+  const delay = (options.backoffMs ?? defaultBackoffMs)(attempt);
+  return new Promise((resolve) => setTimeout(resolve, delay));
+}

package/src/{withRetry.ts → retry/withRetry.ts}

@@ -1,14 +1,5 @@
 import { TransientIOError } from "@flowscripter/pluggable-io-framework-api";
-
-export interface RetryOptions {
-  readonly maxRetries: number;
-  /** Delay in ms before the given retry attempt (1-based). Defaults to `min(200 * 2^attempt, 5000)`. */
-  readonly backoffMs?: (attempt: number) => number;
-}
-
-function defaultBackoffMs(attempt: number): number {
-  return Math.min(200 * 2 ** attempt, 5000);
-}
+import { backoff, type RetryOptions } from "./RetryOptions.ts";
 
 /**
  * Runs `fn`, retrying only on `TransientIOError` up to `options.maxRetries`
@@ -17,7 +8,6 @@ function defaultBackoffMs(attempt: number): number {
  * rethrown immediately.
  */
 export async function withRetry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T> {
-  const backoffMs = options.backoffMs ?? defaultBackoffMs;
   let attempt = 0;
   for (;;) {
     try {
@@ -27,7 +17,7 @@ export async function withRetry<T>(fn: () => Promise<T>, options: RetryOptions):
         throw error;
       }
       attempt += 1;
-      await new Promise((resolve) => setTimeout(resolve, backoffMs(attempt)));
+      await backoff(options, attempt);
     }
   }
 }

package/src/transfer/EntryContext.ts

@@ -0,0 +1,17 @@
+import type { TelemetryHooks } from "@flowscripter/pluggable-io-framework-api";
+import type { TransferOptions } from "./TransferOptions.ts";
+
+/** Per-entry state shared by the transfer strategies. */
+export interface EntryContext {
+  readonly operationId: string;
+  readonly hooks: TelemetryHooks;
+  readonly options: TransferOptions;
+  readonly type: "copy" | "move";
+}
+
+/** Bytes and items moved by one strategy run, and whether `stop` ended it. */
+export interface EntryOutcome {
+  readonly bytes: number;
+  readonly items: number;
+  readonly stopped: boolean;
+}

package/src/transfer/TransferOptions.ts

@@ -0,0 +1,45 @@
+import type { PayloadConverter, TelemetryHooks } from "@flowscripter/pluggable-io-framework-api";
+import type { ConcurrencyLimiter } from "../concurrency/ConcurrencyLimiter.ts";
+import type { RetryOptions } from "../retry/RetryOptions.ts";
+
+export interface TransferOptions {
+  readonly telemetry?: TelemetryHooks;
+  /** Minimum entry size (bytes) before multipart transfer is attempted over plain streaming. */
+  readonly multipartThreshold?: number;
+  /**
+   * The payload converter chosen by negotiation, applied to every item.
+   * Without one, the source and sink must share a payload kind. Set by the
+   * options `createProvidersForTransfer` returns.
+   */
+  readonly converter?: PayloadConverter;
+  /**
+   * The negotiated path description reported in {@link TransferResult.path}.
+   * Set by the options `createProvidersForTransfer` returns; without it the
+   * path is described from the provider kinds.
+   */
+  readonly path?: string;
+  /**
+   * Payload type IDs the sink's factory accepts, which an opened source
+   * handle's `payloadType` must be one of. Providers don't carry their
+   * factory's declarations, so `createProvidersForTransfer` returns them in
+   * its options. Defaults to `["bytes"]`.
+   */
+  readonly writePayloadTypes?: readonly string[];
+  /**
+   * Bounds concurrent multipart parts and recursive/pattern entries.
+   * Defaults to the shared `defaultConcurrencyLimiter` - so two
+   * `copy()`/`move()` calls in the same process share one cap unless a
+   * caller passes its own isolated instance.
+   */
+  readonly concurrencyLimiter?: ConcurrencyLimiter;
+  /** Retry policy for the non-direct transfer path. Defaults to `{ maxRetries: 3 }`. */
+  readonly retry?: RetryOptions;
+  /** Cancels the transfer: the source is cancelled, the sink aborted, and the transfer rejects with an `AbortError`. */
+  readonly signal?: AbortSignal;
+  /** Ends the transfer gracefully: the source is cancelled, the sink closed normally, and the result reports `stopped`. */
+  readonly stop?: AbortSignal;
+  /** When `false`, `directCopy`/`directMove` are never used. Defaults to `true`. */
+  readonly directTransfer?: boolean;
+  /** Maximum leases outstanding on the lease path, capped by the sink's `maxOutstanding`. Defaults to 2. */
+  readonly leaseDepth?: number;
+}

package/src/transfer/TransferResult.ts

@@ -0,0 +1,8 @@
+export interface TransferResult {
+  /** Whether `stop` ended the transfer early (output is truncated for a bounded source). */
+  readonly stopped: boolean;
+  readonly bytes: number;
+  readonly items: number;
+  /** Human-readable description of the negotiated transfer path. */
+  readonly path: string;
+}

package/src/transfer/aggregateResults.ts

@@ -0,0 +1,15 @@
+import type { TransferResult } from "./TransferResult.ts";
+
+/** Sums per-entry results; the aggregate is stopped if any entry was. */
+export function aggregateResults(
+  results: readonly TransferResult[],
+  path: string,
+  stopped: boolean,
+): TransferResult {
+  return {
+    stopped: stopped || results.some((result) => result.stopped),
+    bytes: results.reduce((total, result) => total + result.bytes, 0),
+    items: results.reduce((total, result) => total + result.items, 0),
+    path,
+  };
+}

package/src/transfer/copyMove.ts

@@ -0,0 +1,113 @@
+import {
+  type IOProvider,
+  type LocationTarget,
+  PermanentIOError,
+} from "@flowscripter/pluggable-io-framework-api";
+import { baseName, joinKey } from "../util/keys.ts";
+import { patternTransfer } from "./patternTransfer.ts";
+import { recursiveTransfer } from "./recursiveTransfer.ts";
+import { transferEntry } from "./transferEntry.ts";
+import type { TransferOptions } from "./TransferOptions.ts";
+import type { TransferResult } from "./TransferResult.ts";
+
+async function checkSourceVariant(
+  source: IOProvider,
+  key: string,
+  expectContainer: boolean,
+  variant: string,
+) {
+  const properties = await source.getProperties(key);
+  if (properties.isContainer !== expectContainer) {
+    const actual = properties.isContainer ? "a container" : "an entry";
+    throw new PermanentIOError(`Source "${key}" is declared as ${variant} but is ${actual}`);
+  }
+  return properties;
+}
+
+async function transfer(
+  source: IOProvider,
+  sourceTarget: LocationTarget,
+  sink: IOProvider,
+  destTarget: LocationTarget,
+  options: TransferOptions,
+  type: "copy" | "move",
+): Promise<TransferResult> {
+  if (destTarget.kind === "pattern") {
+    throw new PermanentIOError("A destination cannot be a pattern");
+  }
+  if (sourceTarget.kind === "entry") {
+    const properties = await checkSourceVariant(source, sourceTarget.key, false, "an entry");
+    const destKey =
+      destTarget.kind === "entry"
+        ? destTarget.key
+        : joinKey(sink, destTarget.key, baseName(sourceTarget.key));
+    return transferEntry({
+      source,
+      sourceKey: sourceTarget.key,
+      sink,
+      destKey,
+      properties,
+      options,
+      type,
+      deleteSource: type === "move",
+    });
+  }
+  if (destTarget.kind === "entry") {
+    throw new PermanentIOError(
+      sourceTarget.kind === "container"
+        ? "Cannot transfer a container onto an entry"
+        : "Cannot transfer a pattern of entries onto a single entry",
+    );
+  }
+  if (sourceTarget.kind === "container") {
+    await checkSourceVariant(source, sourceTarget.key, true, "a container");
+    return recursiveTransfer(source, sourceTarget.key, sink, destTarget.key, options, type);
+  }
+  await checkSourceVariant(source, sourceTarget.containerKey, true, "a pattern container");
+  return patternTransfer(
+    source,
+    sourceTarget.containerKey,
+    sourceTarget.pattern,
+    sink,
+    destTarget.key,
+    options,
+    type,
+  );
+}
+
+/**
+ * Copies `sourceTarget` on `source` to `destTarget` on `sink`:
+ * - entry -> entry writes exactly the destination key;
+ * - entry -> container writes `<container>/<source basename>`;
+ * - container -> container copies recursively with `cp -r` semantics;
+ * - pattern -> container copies each matching entry;
+ * - container or pattern -> entry, and any pattern destination, are rejected.
+ *
+ * Each entry uses `directCopy` when eligible (and `options.directTransfer`
+ * is not `false`), otherwise multipart, the lease path or plain streaming.
+ */
+export function copy(
+  source: IOProvider,
+  sourceTarget: LocationTarget,
+  sink: IOProvider,
+  destTarget: LocationTarget,
+  options: TransferOptions = {},
+): Promise<TransferResult> {
+  return transfer(source, sourceTarget, sink, destTarget, options, "copy");
+}
+
+/**
+ * Moves `sourceTarget` on `source` to `destTarget` on `sink`, with the same
+ * target rules as {@link copy}. Non-direct moves copy and then delete the
+ * source. Unbounded sources are rejected, and a stopped move never deletes
+ * its source.
+ */
+export function move(
+  source: IOProvider,
+  sourceTarget: LocationTarget,
+  sink: IOProvider,
+  destTarget: LocationTarget,
+  options: TransferOptions = {},
+): Promise<TransferResult> {
+  return transfer(source, sourceTarget, sink, destTarget, options, "move");
+}

package/src/transfer/leaseTransfer.ts

@@ -0,0 +1,93 @@
+import type {
+  BufferLease,
+  BufferProvider,
+  FillReadable,
+  Item,
+  StreamHandle,
+} from "@flowscripter/pluggable-io-framework-api";
+import { createAbortError } from "../util/abort.ts";
+import type { EntryContext, EntryOutcome } from "./EntryContext.ts";
+
+export const DEFAULT_LEASE_DEPTH = 2;
+
+/** The number of leases the engine keeps outstanding for `writable`. */
+export function leaseDepth(writable: BufferProvider, requested: number | undefined): number {
+  return Math.max(
+    1,
+    Math.min(requested ?? DEFAULT_LEASE_DEPTH, writable.maxOutstanding ?? Infinity),
+  );
+}
+
+function ignore(): void {}
+
+/**
+ * Moves data by having the source fill buffers handed out by the sink:
+ * `acquire -> readInto -> commit`, with up to `depth` leases outstanding so
+ * the next read overlaps earlier commits. `readInto` calls are serialised
+ * and commits happen in acquisition order. Every lease not yet committed is
+ * released on abort, error or end of stream.
+ */
+export async function leaseTransfer(
+  readable: StreamHandle & FillReadable,
+  writable: StreamHandle & BufferProvider,
+  depth: number,
+  context: EntryContext,
+): Promise<EntryOutcome> {
+  const { options, hooks, operationId, type } = context;
+  const outstanding = new Set<BufferLease>();
+  const pending: Promise<void>[] = [];
+  let commitChain: Promise<void> = Promise.resolve();
+  let bytes = 0;
+  let items = 0;
+  let stopped = false;
+  const writer = (writable.stream as WritableStream<Item>).getWriter();
+
+  try {
+    for (;;) {
+      if (options.signal?.aborted) throw createAbortError();
+      if (options.stop?.aborted) {
+        stopped = true;
+        break;
+      }
+      while (pending.length >= depth) {
+        await pending.shift();
+      }
+      const lease = await writable.acquire();
+      outstanding.add(lease);
+      const length = await readable.readInto(lease);
+      if (length === null) {
+        outstanding.delete(lease);
+        lease.release();
+        break;
+      }
+      bytes += length;
+      items += 1;
+      const committed = commitChain.then(async () => {
+        await lease.commit(length);
+        outstanding.delete(lease);
+      });
+      committed.catch(ignore);
+      commitChain = committed;
+      pending.push(committed);
+      hooks.onProgress?.({
+        operationId,
+        type,
+        bytesProcessed: bytes,
+        totalBytes: undefined,
+      });
+    }
+    await commitChain;
+    await writer.close();
+    if (!stopped) {
+      await (readable.stream as ReadableStream<Item>).cancel().catch(ignore);
+    }
+    return { bytes, items, stopped };
+  } catch (error) {
+    for (const lease of outstanding) {
+      lease.release();
+    }
+    await writer.abort(error).catch(ignore);
+    await (readable.stream as ReadableStream<Item>).cancel(error).catch(ignore);
+    throw error;
+  }
+}

package/src/transfer/multipartTransfer.ts

@@ -0,0 +1,119 @@
+import {
+  type IOProvider,
+  type Item,
+  type Part,
+  type RangeReadable,
+  type StreamHandle,
+  TransientIOError,
+} from "@flowscripter/pluggable-io-framework-api";
+import type { ConcurrencyLimiter } from "../concurrency/ConcurrencyLimiter.ts";
+import { mapAsyncIterableConcurrently } from "../concurrency/mapAsyncIterableConcurrently.ts";
+import { backoff, DEFAULT_RETRY } from "../retry/RetryOptions.ts";
+import { createAbortError } from "../util/abort.ts";
+import { applyPayloadConverter } from "../util/applyPayloadConverter.ts";
+import { itemLength } from "../util/itemLength.ts";
+import type { EntryContext, EntryOutcome } from "./EntryContext.ts";
+import { rangeReadableMultipartReader } from "./rangeReadableMultipartReader.ts";
+
+export interface MultipartTransferInput {
+  readonly readable: StreamHandle & RangeReadable;
+  readonly sink: IOProvider;
+  readonly writer: { write(parts: AsyncIterable<Part>): Promise<void> };
+  readonly totalBytes: number;
+  readonly partSize: number;
+  readonly limiter: ConcurrencyLimiter;
+  readonly context: EntryContext;
+}
+
+/**
+ * Reads parts with `readRange` and hands them to the sink's multipart
+ * writer, bounded by `limiter`. A part whose read fails with a
+ * `TransientIOError` is re-read on its own, up to `retry.maxRetries` times,
+ * within the same upload. `stop` ends the transfer after the parts already
+ * started; `signal` aborts it.
+ */
+export async function multipartTransfer(input: MultipartTransferInput): Promise<EntryOutcome> {
+  const { readable, sink, writer, totalBytes, partSize, limiter, context } = input;
+  const { options, hooks, operationId, type } = context;
+  const retry = options.retry ?? DEFAULT_RETRY;
+  let bytes = 0;
+  let items = 0;
+  let stopped = false;
+
+  async function readPart(sourcePart: Part): Promise<Item[]> {
+    const partOperationId = crypto.randomUUID();
+    const end = Math.min(sourcePart.offset + partSize, totalBytes);
+    let stream = sourcePart.stream as ReadableStream<Item>;
+    let attempt = 0;
+    for (;;) {
+      const reader = applyPayloadConverter(
+        stream,
+        readable.kind,
+        sink.kind,
+        options.converter,
+      ).getReader();
+      const partItems: Item[] = [];
+      let partBytes = 0;
+      try {
+        for (;;) {
+          if (options.signal?.aborted) {
+            await reader.cancel().catch(() => {});
+            throw createAbortError();
+          }
+          const { done, value } = await reader.read();
+          if (done) break;
+          partItems.push(value);
+          partBytes += itemLength(value);
+          hooks.onProgress?.({
+            operationId: partOperationId,
+            parentOperationId: operationId,
+            type,
+            bytesProcessed: partBytes,
+          });
+        }
+        bytes += partBytes;
+        items += partItems.length;
+        hooks.onProgress?.({ operationId, type, bytesProcessed: bytes, totalBytes });
+        return partItems;
+      } catch (error) {
+        if (!(error instanceof TransientIOError) || attempt >= retry.maxRetries) {
+          throw error;
+        }
+        attempt += 1;
+        await backoff(retry, attempt);
+        stream = (await readable.readRange(sourcePart.offset, end)) as ReadableStream<Item>;
+      }
+    }
+  }
+
+  async function transferPart(sourcePart: Part): Promise<Part> {
+    const partItems = await readPart(sourcePart);
+    return {
+      index: sourcePart.index,
+      offset: sourcePart.offset,
+      kind: sink.kind,
+      stream: new ReadableStream<Item>({
+        start(controller) {
+          for (const item of partItems) controller.enqueue(item);
+          controller.close();
+        },
+      }),
+      complete: () => sourcePart.complete(),
+    };
+  }
+
+  async function* sourceParts(): AsyncGenerator<Part> {
+    for await (const part of rangeReadableMultipartReader(readable, totalBytes, partSize)) {
+      if (options.signal?.aborted) throw createAbortError();
+      if (options.stop?.aborted) {
+        stopped = true;
+        await (part.stream as ReadableStream<Item>).cancel().catch(() => {});
+        return;
+      }
+      yield part;
+    }
+  }
+
+  await writer.write(mapAsyncIterableConcurrently(sourceParts(), transferPart, limiter));
+  return { bytes, items, stopped };
+}

package/src/transfer/negotiatePartSize.ts

@@ -0,0 +1,40 @@
+import type { IOProvider, PartSizeConstraints } from "@flowscripter/pluggable-io-framework-api";
+
+const DEFAULT_PART_SIZE = 8 * 1024 * 1024;
+
+const UNCONSTRAINED_PART_SIZE: PartSizeConstraints = {
+  minPartSize: 0,
+  maxPartSize: Infinity,
+  maxParts: Infinity,
+  defaultPartSize: DEFAULT_PART_SIZE,
+};
+
+/**
+ * Reconciles `source`'s and `sink`'s {@link PartSizeConstraints} for a
+ * transfer of `totalSize` bytes into a single part size satisfying both.
+ * Returns `undefined` when the bounds are mutually infeasible (source's
+ * minimum exceeds sink's maximum) - the caller should fall back to plain
+ * streaming rather than throwing.
+ */
+export function negotiatePartSize(
+  source: IOProvider,
+  sink: IOProvider,
+  totalSize: number,
+): number | undefined {
+  const sourceConstraints = source.getPartSizeConstraints?.(totalSize) ?? UNCONSTRAINED_PART_SIZE;
+  const sinkConstraints = sink.getPartSizeConstraints?.(totalSize) ?? UNCONSTRAINED_PART_SIZE;
+  const minPartSize = Math.max(sourceConstraints.minPartSize, sinkConstraints.minPartSize);
+  const maxPartSize = Math.min(sourceConstraints.maxPartSize, sinkConstraints.maxPartSize);
+  const maxParts = Math.min(sourceConstraints.maxParts, sinkConstraints.maxParts);
+  if (minPartSize > maxPartSize) {
+    return undefined;
+  }
+  const byMaxParts = Math.ceil(totalSize / maxParts);
+  const candidate = Math.max(
+    minPartSize,
+    sourceConstraints.defaultPartSize,
+    sinkConstraints.defaultPartSize,
+    byMaxParts,
+  );
+  return Math.min(candidate, maxPartSize);
+}