@beam-network/sdk 0.2.16 → 0.2.18

package/dist/client.js

@@ -1,4 +1,4 @@
-import { abortMultipartUpload, computeChunksContentMd5, createMultipartUpload, nowIso, prepareProviderDestination, prepareProviderSource, prepareProviderSourceForPlan, isS3CompatibleProvider, listPartsPageMarker, listPartsVerifyMarker, signAbortMultipartUpload, signCompleteMultipartUpload, signDeleteObject, signDestinationRoute, signListMultipartUpload, signListObjects, signUploadPartCopy } from "./provider-signing.js";
+import { abortMultipartUpload, createMultipartUpload, nowIso, prepareProviderDestination, prepareProviderSource, listPartsPageMarker, listPartsVerifyMarker, signAbortMultipartUpload, signCompleteMultipartUpload, signDeleteObject, signDestinationRoute, signListMultipartUpload, signListObjects, signUploadPartCopy } from "./provider-signing.js";
 import { BeamTransferControl, BEAM_DEFAULT_NATS_URL } from "./nats-control.js";
 export { BEAM_DEFAULT_NATS_URL };
 export class BeamApiError extends Error {
@@ -16,6 +16,7 @@ export class BeamClient {
     natsUrl;
     fetchImpl;
     control;
+    recoverySigners = new Map();
     constructor(options = {}) {
         if (!options.apiKey?.trim()) {
             throw new Error("apiKey is required.");
@@ -37,7 +38,8 @@ export class BeamClient {
             throw new Error("A fetch implementation is required.");
         }
     }
-    close() {
+    async close() {
+        this.stopAllRecoverySigners();
         return this.control.close();
     }
     createRawTransfer(input) {
@@ -52,7 +54,6 @@ export class BeamClient {
             chunk_hashes: input.chunkHashes,
             callbacks: input.callbacks,
             test_mode: input.testMode || undefined,
-            experimental: input.experimental || undefined,
             progressive_mode: input.progressiveMode || undefined,
             signed_url_flow: input.signedUrlFlow
         });
@@ -69,9 +70,14 @@ export class BeamClient {
         validateId(transferId, "transferId");
         return this.control.request("transfer.distribute", { transfer_id: transferId }, transferId);
     }
-    cancelTransfer(transferId) {
+    async cancelTransfer(transferId) {
         validateId(transferId, "transferId");
-        return this.control.request("transfer.cancel", { transfer_id: transferId }, transferId);
+        try {
+            return await this.control.request("transfer.cancel", { transfer_id: transferId }, transferId);
+        }
+        finally {
+            this.stopRecoverySigner(transferId);
+        }
     }
     planTransfer(input) {
         return this.control.request("transfer.plan", compact({
@@ -79,7 +85,6 @@ export class BeamClient {
             destinations: input.destinations,
             name: input.name,
             test_mode: input.testMode || undefined,
-            experimental: input.experimental || undefined,
             urls_expires_at: input.urlsExpiresAt,
             signed_url_flow: input.signedUrlFlow
         }));
@@ -92,36 +97,25 @@ export class BeamClient {
             destinations: input.destinations,
             name: input.name,
             test_mode: input.testMode || undefined,
-            experimental: input.experimental || undefined,
             urls_expires_at: input.urlsExpiresAt,
             signed_url_flow: input.signedUrlFlow
         }), transferId);
     }
     async attachSignedUrls(transferId, input) {
         validateId(transferId, "transferId");
-        const attachmentId = newTransferId();
-        await this.control.request("transfer.attach_signed_urls.begin", compact({
-            transfer_id: transferId,
-            attachment_id: attachmentId,
-            total_routes: input.chunkRoutes.length,
-            urls_expires_at: input.urlsExpiresAt
-        }), transferId);
-        const chunks = this.control.splitRoutesForPayload("transfer.attach_signed_urls.chunk", {
-            transfer_id: transferId,
-            attachment_id: attachmentId
-        }, input.chunkRoutes);
-        for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex += 1) {
-            await this.control.request("transfer.attach_signed_urls.chunk", {
-                transfer_id: transferId,
-                attachment_id: attachmentId,
-                chunk_index: chunkIndex,
-                chunk_routes: chunks[chunkIndex]
-            }, transferId);
+        const stream = new RouteStreamSender(this.control, {
+            transferId,
+            totalRoutes: input.chunkRoutes.length,
+            totalChunks: countDistinctRouteChunks(input.chunkRoutes),
+            urlsExpiresAt: input.urlsExpiresAt,
+            signedUrlFlow: input.signedUrlFlow ?? "signed_url_v1",
+            autoDistribute: input.autoDistribute ?? true
+        });
+        await stream.begin();
+        for (const route of input.chunkRoutes) {
+            await stream.addRoute(route);
         }
-        return this.control.request("transfer.attach_signed_urls.commit", {
-            transfer_id: transferId,
-            attachment_id: attachmentId
-        }, transferId);
+        return stream.complete();
     }
     async prepareProviderTransfer(input) {
         const expiresIn = input.expiresIn ?? 3600;
@@ -135,93 +129,19 @@ export class BeamClient {
             }
             destinationsById.set(preparedDestination.destination_id, destination);
         });
-        const checksumCache = new ChunkChecksumCache({
-            concurrency: input.checksumReadConcurrency ?? 8,
-            expiresIn,
-            fetchImpl: this.fetchImpl,
-            provider: input.checksumProvider,
-            groupSizeBytes: input.checksumGroupSizeBytes ?? 256 * 1024 * 1024,
-            readTimeoutMs: input.checksumReadTimeoutMs,
-            onEvent: input.onChecksumEvent,
-            throwIfCancelled: () => input.throwIfCancelled?.()
+        await input.throwIfCancelled?.();
+        const preparedSources = await Promise.all(input.sources.map((source, index) => prepareProviderSource(source, { index, expiresIn, fetchImpl: this.fetchImpl })));
+        await input.throwIfCancelled?.();
+        await input.onBeforeTransferPrepare?.();
+        const prepared = await this.prepareTransfer({
+            sources: preparedSources,
+            destinations: preparedDestinations,
+            name: input.name,
+            testMode: input.testMode,
+            signedUrlFlow: requestedSignedUrlFlow
         });
-        let preparedSources;
-        let prepared;
-        if (requestedSignedUrlFlow === "signed_url_v1") {
-            await input.throwIfCancelled?.();
-            const plannedSources = await Promise.all(input.sources.map((source, index) => prepareProviderSourceForPlan(source, { index, fetchImpl: this.fetchImpl })));
-            const planned = await this.planTransfer({
-                sources: plannedSources,
-                destinations: preparedDestinations,
-                name: input.name,
-                testMode: input.testMode,
-                experimental: input.experimental,
-                signedUrlFlow: requestedSignedUrlFlow
-            });
-            if (!planned.success) {
-                return failedPlanAsPrepareResponse(planned);
-            }
-            await input.onPlanned?.(planned);
-            await input.throwIfCancelled?.();
-            const plannedSourcesById = mapSourcesByPreparedId(plannedSources, input.sources);
-            const chunksBySource = checksumChunksBySource(planned.chunk_plan, destinationsById);
-            const totalWarmupChunks = [...chunksBySource.values()].reduce((sum, chunks) => sum + chunks.length, 0);
-            const totalWarmupBytes = [...chunksBySource.values()].reduce((sum, chunks) => sum + chunks.reduce((chunkSum, chunk) => chunkSum + chunk.chunk_size, 0), 0);
-            if (totalWarmupChunks > 0) {
-                const startedAt = Date.now();
-                await emitChecksumEvent(input, {
-                    event: "checksum_warmup_started",
-                    sourceId: "all",
-                    chunkCount: totalWarmupChunks,
-                    bytes: totalWarmupBytes
-                });
-                for (const [sourceId, chunks] of chunksBySource) {
-                    await input.throwIfCancelled?.();
-                    const source = plannedSourcesById.get(sourceId);
-                    if (!source) {
-                        throw new Error(`BeamCore planned unknown source_id: ${sourceId}`);
-                    }
-                    await checksumCache.ensureMany(source, chunks);
-                }
-                await emitChecksumEvent(input, {
-                    event: "checksum_warmup_completed",
-                    sourceId: "all",
-                    chunkCount: totalWarmupChunks,
-                    bytes: totalWarmupBytes,
-                    durationMs: Date.now() - startedAt
-                });
-            }
-            await input.throwIfCancelled?.();
-            checksumCache.seal();
-            preparedSources = await Promise.all(input.sources.map((source, index) => prepareProviderSource(source, { index, expiresIn, fetchImpl: this.fetchImpl })));
-            await input.onBeforeTransferPrepare?.();
-            prepared = await this.prepareTransfer({
-                sources: preparedSources,
-                destinations: preparedDestinations,
-                name: input.name,
-                testMode: input.testMode,
-                experimental: input.experimental,
-                signedUrlFlow: requestedSignedUrlFlow
-            });
-            if (!prepared.success) {
-                return prepared;
-            }
-            assertPreparedTransferMatchesPlan(planned, prepared);
-        }
-        else {
-            preparedSources = await Promise.all(input.sources.map((source, index) => prepareProviderSource(source, { index, expiresIn, fetchImpl: this.fetchImpl })));
-            await input.onBeforeTransferPrepare?.();
-            prepared = await this.prepareTransfer({
-                sources: preparedSources,
-                destinations: preparedDestinations,
-                name: input.name,
-                testMode: input.testMode,
-                experimental: input.experimental,
-                signedUrlFlow: requestedSignedUrlFlow
-            });
-            if (!prepared.success) {
-                return prepared;
-            }
+        if (!prepared.success) {
+            return prepared;
         }
         await input.onPrepared?.(prepared);
         await input.throwIfCancelled?.(prepared.transfer_id);
@@ -234,13 +154,26 @@ export class BeamClient {
             sourcesById.set(preparedSource.source_id, source);
         });
         const signedUrlFlow = prepared.signed_url_flow ?? requestedSignedUrlFlow;
-        if (signedUrlFlow === "signed_url_v1") {
-            const chunksBySource = checksumChunksBySource(prepared.chunk_plan, destinationsById);
-            checksumCache.assertManyWarmed(chunksBySource);
-        }
-        const routes = [];
+        const routeStream = new RouteStreamSender(this.control, {
+            transferId: prepared.transfer_id,
+            totalRoutes: countRoutesInChunkPlan(prepared.chunk_plan),
+            totalChunks: prepared.logical_chunks ?? prepared.total_chunks ?? prepared.chunk_plan.length,
+            signedUrlFlow,
+            autoDistribute: input.distribute !== false
+        });
         const multipartUploads = new Map();
+        await this.startProviderRouteRecoverySigner({
+            prepared,
+            sourcesById,
+            destinationsById,
+            multipartUploads,
+            expiresIn,
+            signedUrlFlow
+        });
+        let routeStreamStarted = false;
         try {
+            await routeStream.begin();
+            routeStreamStarted = true;
             for (const chunk of prepared.chunk_plan) {
                 await input.throwIfCancelled?.(prepared.transfer_id);
                 for (const target of chunk.destinations) {
@@ -290,7 +223,7 @@ export class BeamClient {
                         }
                         multipartUploads.set(multipartKey, upload);
                     }
-                    routes.push(await this.signProviderRoute({
+                    await routeStream.addRoute(await this.signProviderRoute({
                         chunk,
                         target,
                         source,
@@ -301,35 +234,24 @@ export class BeamClient {
                         finalObjectKey,
                         partNumber: typeof metadata.part_number === "number"
                             ? metadata.part_number
-                            : chunk.source_chunk_index + 1,
-                        signedUrlFlow,
-                        checksumCache
+                            : chunk.chunk_index * 3 + 1,
+                        signedUrlFlow
                     }));
                 }
             }
-        }
-        catch (error) {
-            await abortCreatedUploads(multipartUploads);
-            throw error;
-        }
-        try {
-            await input.throwIfCancelled?.(prepared.transfer_id);
-            const attached = await this.attachSignedUrls(prepared.transfer_id, {
-                chunkRoutes: routes,
-                transferKey: prepared.transfer_key
-            });
+            const attached = await routeStream.complete();
             if (!attached.success) {
-                throw new Error(attached.error ?? attached.message ?? "attach signed URLs failed");
+                throw new Error(attached.error ?? attached.message ?? "route stream failed");
             }
         }
         catch (error) {
+            this.stopRecoverySigner(prepared.transfer_id);
             await abortCreatedUploads(multipartUploads);
+            if (routeStreamStarted) {
+                await cancelTransferAfterRouteStreamFailure(this, prepared.transfer_id, error);
+            }
             throw error;
         }
-        if (input.distribute !== false) {
-            await input.throwIfCancelled?.(prepared.transfer_id);
-            await this.distributeTransfer(prepared.transfer_id);
-        }
         return prepared;
     }
     async signProviderRoute(input) {
@@ -350,7 +272,6 @@ export class BeamClient {
             throw new Error("destination signing target is missing object_key");
         }
         if (input.signedUrlFlow === "signed_url_v1") {
-            const contentMd5 = await input.checksumCache.get(input.source, input.chunk);
             const partVerifyUrl = await signListMultipartUpload(input.destination, input.finalObjectKey, input.upload.uploadId, input.expiresIn, { maxParts: 1, partNumberMarker: listPartsVerifyMarker(input.partNumber) });
             const listPageUrl = await signListMultipartUpload(input.destination, input.finalObjectKey, input.upload.uploadId, input.expiresIn, { maxParts: 1000, partNumberMarker: listPartsPageMarker(input.partNumber) });
             return signDestinationRoute({
@@ -367,7 +288,6 @@ export class BeamClient {
                 listUrl: input.upload.listUrl,
                 partVerifyUrl,
                 listPageUrl,
-                contentMd5,
                 transferId: input.transferId,
                 multipartGroupId: input.upload.multipartGroupId,
                 multipartCreatedAt: input.upload.multipartCreatedAt,
@@ -414,6 +334,80 @@ export class BeamClient {
             fetchImpl: this.fetchImpl
         });
     }
+    async startProviderRouteRecoverySigner(input) {
+        this.stopRecoverySigner(input.prepared.transfer_id);
+        const stop = await this.control.serveRouteRecoverySigner(input.prepared.transfer_id, async (payload) => {
+            const routes = [];
+            for (const requested of payload.chunks) {
+                const chunk = input.prepared.chunk_plan.find((candidate) => candidate.chunk_index === requested.chunk_index && candidate.source_id === requested.source_id);
+                if (!chunk) {
+                    throw new Error(`recovery signing chunk not found: ${requested.source_id}:${requested.chunk_index}`);
+                }
+                const target = chunk.destinations.find((candidate) => candidate.destination_id === requested.destination_id);
+                if (!target) {
+                    throw new Error(`recovery signing destination not found: ${requested.destination_id}`);
+                }
+                const source = input.sourcesById.get(requested.source_id);
+                const destination = input.destinationsById.get(requested.destination_id);
+                if (!source || !destination) {
+                    throw new Error("recovery signing provider configuration missing");
+                }
+                const upload = input.multipartUploads.get(requested.multipart_group_id) ?? input.multipartUploads.get(`${input.prepared.transfer_id}:${requested.destination_id}:${requested.source_id}:${requested.final_object_key}`);
+                if (!upload) {
+                    throw new Error(`recovery signing multipart upload state missing for ${requested.multipart_group_id}`);
+                }
+                const metadata = {
+                    ...(target.metadata ?? {}),
+                    ...(requested.destination_metadata ?? {}),
+                    transfer_id: input.prepared.transfer_id,
+                    final_object_key: requested.final_object_key,
+                    upload_id: requested.upload_id ?? upload.uploadId,
+                    multipart_group_id: requested.multipart_group_id,
+                    multipart_created_at: requested.multipart_created_at ?? upload.multipartCreatedAt,
+                    delivery_index: requested.delivery_index,
+                    part_number: requested.part_number,
+                    logical_attempt_index: requested.logical_attempt_index,
+                    attempt_slot: requested.attempt_slot,
+                    route_generation_id: requested.route_generation_id
+                };
+                routes.push(await this.signProviderRoute({
+                    chunk,
+                    target: {
+                        ...target,
+                        object_key: target.object_key ?? requested.final_object_key,
+                        metadata
+                    },
+                    source,
+                    destination,
+                    expiresIn: input.expiresIn,
+                    upload,
+                    transferId: input.prepared.transfer_id,
+                    finalObjectKey: requested.final_object_key,
+                    partNumber: requested.part_number,
+                    signedUrlFlow: input.signedUrlFlow
+                }));
+            }
+            return {
+                transfer_id: payload.transfer_id,
+                route_generation_id: payload.route_generation_id,
+                signed_at: nowIso(),
+                chunk_routes: routes
+            };
+        });
+        this.recoverySigners.set(input.prepared.transfer_id, stop);
+    }
+    stopRecoverySigner(transferId) {
+        const stop = this.recoverySigners.get(transferId);
+        if (!stop)
+            return;
+        stop();
+        this.recoverySigners.delete(transferId);
+    }
+    stopAllRecoverySigners() {
+        for (const transferId of [...this.recoverySigners.keys()]) {
+            this.stopRecoverySigner(transferId);
+        }
+    }
     async createAndDistribute(input) {
         const transfer = await this.createRawTransfer(input);
         if (transfer.success) {
@@ -428,12 +422,15 @@ export class BeamClient {
         while (true) {
             const status = await this.transferStatus(transferId);
             if (status.status === "completed") {
+                this.stopRecoverySigner(transferId);
                 return status;
             }
             if (status.status === "failed") {
+                this.stopRecoverySigner(transferId);
                 throw new Error(`Transfer failed: ${status.error_message ?? "unknown error"}`);
             }
             if (status.status === "cancelled") {
+                this.stopRecoverySigner(transferId);
                 throw new Error("Transfer cancelled");
             }
             if (Date.now() - startedAt >= timeoutMs) {
@@ -443,284 +440,124 @@ export class BeamClient {
         }
     }
 }
-function checksumChunksBySource(chunkPlan, destinationsById) {
-    const chunksBySource = new Map();
-    for (const chunk of chunkPlan) {
-        const needsChecksum = chunk.destinations.some((target) => {
-            const destination = destinationsById.get(target.destination_id);
-            return destination ? isS3CompatibleProvider(destination) : false;
-        });
-        if (!needsChecksum)
-            continue;
-        const chunks = chunksBySource.get(chunk.source_id) ?? [];
-        chunks.push(chunk);
-        chunksBySource.set(chunk.source_id, chunks);
-    }
-    return chunksBySource;
-}
-function mapSourcesByPreparedId(preparedSources, providerSources) {
-    const sourcesById = new Map();
-    preparedSources.forEach((preparedSource, index) => {
-        const source = providerSources[index];
-        if (!source) {
-            throw new Error(`missing provider source config for planned source ${preparedSource.source_id}`);
-        }
-        sourcesById.set(preparedSource.source_id, source);
-    });
-    return sourcesById;
-}
-function failedPlanAsPrepareResponse(plan) {
-    return {
-        success: false,
-        transfer_id: "",
-        chunk_size: plan.chunk_size,
-        total_size: plan.total_size,
-        total_sources: plan.total_sources,
-        total_destinations: plan.total_destinations,
-        logical_chunks: plan.logical_chunks,
-        total_chunks: plan.total_chunks,
-        chunk_plan: plan.chunk_plan ?? [],
-        signed_url_flow: plan.signed_url_flow,
-        error: plan.error,
-        message: plan.message
-    };
-}
-function assertPreparedTransferMatchesPlan(plan, prepared) {
-    const summaryMatches = plan.chunk_size === prepared.chunk_size &&
-        plan.total_size === prepared.total_size &&
-        plan.total_sources === prepared.total_sources &&
-        plan.total_destinations === prepared.total_destinations &&
-        plan.logical_chunks === prepared.logical_chunks &&
-        plan.total_chunks === prepared.total_chunks;
-    if (!summaryMatches || planSignature(plan.chunk_plan) !== planSignature(prepared.chunk_plan)) {
-        throw new Error("prepared transfer chunk plan does not match preflight checksum plan");
-    }
-}
-function planSignature(chunks) {
-    return JSON.stringify(chunks.map((chunk) => ({
-        chunk_index: chunk.chunk_index,
-        source_id: chunk.source_id,
-        source_chunk_index: chunk.source_chunk_index,
-        source_offset: chunk.source_offset,
-        chunk_size: chunk.chunk_size,
-        destinations: chunk.destinations.map((target) => {
-            const metadata = target.metadata ?? {};
-            return {
-                destination_id: target.destination_id,
-                provider: target.provider,
-                final_object_key: typeof metadata.final_object_key === "string" ? metadata.final_object_key : target.object_key,
-                part_number: typeof metadata.part_number === "number" ? metadata.part_number : undefined,
-                delivery_index: typeof metadata.delivery_index === "number" ? metadata.delivery_index : undefined
-            };
-        })
-    })));
-}
-async function emitChecksumEvent(input, event) {
-    if (!input.onChecksumEvent)
-        return;
-    await input.onChecksumEvent(event);
-}
-class ChunkChecksumCache {
+// Target route-stream batches at 512 signed routes. The transport still splits
+// earlier when the encoded NATS request would exceed maxPayloadBytes.
+const ROUTE_STREAM_TARGET_BATCH_ROUTES = 512;
+class RouteStreamSender {
+    control;
     options;
-    queue = [];
-    cache = new Map();
-    active = 0;
-    sealed = false;
-    constructor(options) {
+    streamId = newTransferId();
+    checksum = new RouteKeysChecksum();
+    batch = [];
+    batchIndex = 0;
+    constructor(control, options) {
+        this.control = control;
         this.options = options;
     }
-    preloadMany(source, chunks) {
-        if (this.sealed) {
-            const missing = this.uniqueChunks(chunks).filter((chunk) => !this.cache.has(this.key(chunk)));
-            if (missing.length) {
-                throw new Error(`checksum cache missing ${missing.length} chunk(s) after preflight warmup; refusing post-prepare source reads`);
-            }
-            return;
-        }
-        const pending = this.uniqueChunks(chunks).filter((chunk) => !this.cache.has(this.key(chunk)));
-        for (const chunk of pending) {
-            this.cache.set(this.key(chunk), deferredChecksum());
-        }
-        for (const group of this.groupChunks(pending)) {
-            void this.run(() => this.fillGroup(source, group)).catch(() => undefined);
-        }
-    }
-    async ensureMany(source, chunks) {
-        const unique = this.uniqueChunks(chunks);
-        this.preloadMany(source, unique);
-        await Promise.all(unique.map((chunk) => this.get(source, chunk)));
-    }
-    get(source, chunk) {
-        const key = this.key(chunk);
-        let existing = this.cache.get(key);
-        if (!existing) {
-            if (this.sealed) {
-                return Promise.reject(new Error(`checksum cache missing ${key} after preflight warmup; refusing post-prepare source read`));
-            }
-            existing = deferredChecksum();
-            this.cache.set(key, existing);
-            void this.run(() => this.fillGroup(source, [chunk])).catch(() => undefined);
-        }
-        return existing.promise;
-    }
-    async fillGroup(source, chunks) {
-        const unresolved = new Set(chunks.map((chunk) => this.key(chunk)));
-        try {
-            await this.options.throwIfCancelled?.();
-            const misses = [];
-            for (const chunk of chunks) {
-                const key = this.key(chunk);
-                const deferred = this.cache.get(key);
-                if (!deferred)
-                    continue;
-                const cached = await this.options.provider?.getContentMd5({ source, chunk, algorithm: "content-md5" }).catch(() => undefined);
-                if (cached) {
-                    await this.emit({ event: "checksum_cache_hit", sourceId: chunk.source_id, sourceChunkIndex: chunk.source_chunk_index, bytes: chunk.chunk_size });
-                    deferred.resolve(cached);
-                    unresolved.delete(key);
-                }
-                else {
-                    await this.emit({ event: "checksum_cache_miss", sourceId: chunk.source_id, sourceChunkIndex: chunk.source_chunk_index, bytes: chunk.chunk_size });
-                    misses.push(chunk);
-                }
-            }
-            if (!misses.length)
-                return;
-            await this.options.throwIfCancelled?.();
-            const startedAt = Date.now();
-            const checksums = await computeChunksContentMd5({
-                source,
-                chunks: misses,
-                expiresIn: this.options.expiresIn,
-                fetchImpl: this.options.fetchImpl,
-                groupSizeBytes: this.options.groupSizeBytes,
-                readTimeoutMs: this.options.readTimeoutMs
-            });
-            for (const chunk of misses) {
-                await this.options.throwIfCancelled?.();
-                const checksum = checksums.get(chunk.source_chunk_index);
-                if (!checksum)
-                    throw new Error(`checksum missing for source chunk ${chunk.source_chunk_index}`);
-                await this.options.provider?.setContentMd5?.({ source, chunk, algorithm: "content-md5", contentMd5: checksum });
-                const deferred = this.cache.get(this.key(chunk));
-                deferred?.resolve(checksum);
-                unresolved.delete(this.key(chunk));
-                await this.emit({ event: "checksum_cold_chunk_cached", sourceId: chunk.source_id, sourceChunkIndex: chunk.source_chunk_index, bytes: chunk.chunk_size });
-            }
-            await this.emit({
-                event: "checksum_cold_group_completed",
-                sourceId: misses[0]?.source_id ?? source.id ?? "source",
-                chunkCount: misses.length,
-                bytes: misses.reduce((sum, chunk) => sum + chunk.chunk_size, 0),
-                durationMs: Date.now() - startedAt
-            });
-        }
-        catch (error) {
-            for (const key of unresolved) {
-                this.cache.get(key)?.reject(error);
-            }
-            throw error;
+    async begin() {
+        await this.control.request("transfer.route_stream.begin", compact({
+            transfer_id: this.options.transferId,
+            stream_id: this.streamId,
+            total_routes: this.options.totalRoutes,
+            total_chunks: this.options.totalChunks,
+            urls_expires_at: this.options.urlsExpiresAt,
+            signed_url_flow: this.options.signedUrlFlow,
+            auto_distribute: this.options.autoDistribute
+        }), this.options.transferId);
+    }
+    async addRoute(route) {
+        await this.checksum.add(routeKeyForSignedRoute(route));
+        this.batch.push(route);
+        if (this.batch.length >= ROUTE_STREAM_TARGET_BATCH_ROUTES) {
+            await this.flush();
         }
     }
-    uniqueChunks(chunks) {
-        const seen = new Set();
-        const output = [];
+    async complete() {
+        await this.flush();
+        return this.control.request("transfer.route_stream.complete", {
+            transfer_id: this.options.transferId,
+            stream_id: this.streamId,
+            expected_batches: this.batchIndex,
+            expected_routes: this.options.totalRoutes,
+            route_keys_checksum: this.checksum.value()
+        }, this.options.transferId);
+    }
+    async flush() {
+        if (!this.batch.length)
+            return;
+        const routes = this.batch.splice(0, this.batch.length);
+        const chunks = this.control.splitRoutesForPayload("transfer.route_stream.batch", {
+            transfer_id: this.options.transferId,
+            stream_id: this.streamId,
+            batch_id: `${this.streamId}:estimate`,
+            batch_index: this.batchIndex
+        }, routes);
         for (const chunk of chunks) {
-            const key = this.key(chunk);
-            if (seen.has(key))
-                continue;
-            seen.add(key);
-            output.push(chunk);
+            const batchIndex = this.batchIndex;
+            this.batchIndex += 1;
+            await this.control.request("transfer.route_stream.batch", {
+                transfer_id: this.options.transferId,
+                stream_id: this.streamId,
+                batch_id: `${this.streamId}:${batchIndex}`,
+                batch_index: batchIndex,
+                chunk_routes: chunk,
+                route_count: chunk.length,
+                route_keys_checksum: await routeKeysChecksum(chunk.map(routeKeyForSignedRoute))
+            }, this.options.transferId);
         }
-        return output.sort((a, b) => a.source_offset - b.source_offset || a.source_chunk_index - b.source_chunk_index);
     }
-    groupChunks(chunks) {
-        const groups = [];
-        let current = [];
-        let groupStart = 0;
-        let groupEnd = 0;
-        const maxBytes = Math.max(1, Math.floor(this.options.groupSizeBytes));
-        for (const chunk of chunks) {
-            const chunkStart = chunk.source_offset;
-            const chunkEnd = chunk.source_offset + chunk.chunk_size;
-            const startsNewGroup = current.length === 0 || chunkStart !== groupEnd || chunkEnd - groupStart > maxBytes;
-            if (startsNewGroup) {
-                if (current.length)
-                    groups.push(current);
-                current = [chunk];
-                groupStart = chunkStart;
-                groupEnd = chunkEnd;
-            }
-            else {
-                current.push(chunk);
-                groupEnd = chunkEnd;
-            }
+}
+class RouteKeysChecksum {
+    bytes = new Uint8Array(32);
+    count = 0;
+    async add(routeKeyValue) {
+        const digest = await sha256Bytes(routeKeyValue);
+        for (let index = 0; index < this.bytes.length; index += 1) {
+            this.bytes[index] ^= digest[index] ?? 0;
         }
-        if (current.length)
-            groups.push(current);
-        return groups;
-    }
-    key(chunk) {
-        return `${chunk.source_id}:${chunk.source_chunk_index}`;
+        this.count += 1;
     }
-    seal() {
-        this.sealed = true;
+    value() {
+        return `sha256-xor-v1:${this.count}:${hex(this.bytes)}`;
     }
-    assertManyWarmed(chunksBySource) {
-        const missing = [];
-        for (const chunks of chunksBySource.values()) {
-            for (const chunk of this.uniqueChunks(chunks)) {
-                if (!this.cache.has(this.key(chunk)))
-                    missing.push(this.key(chunk));
-            }
-        }
-        if (missing.length) {
-            throw new Error(`checksum cache missing ${missing.length} chunk(s) after preflight warmup; refusing post-prepare source reads`);
-        }
-    }
-    run(task) {
-        return new Promise((resolve, reject) => {
-            const start = () => {
-                this.active += 1;
-                task().then(resolve, reject).finally(() => {
-                    this.active -= 1;
-                    this.queue.shift()?.();
-                });
-            };
-            if (this.active < Math.max(1, this.options.concurrency))
-                start();
-            else
-                this.queue.push(start);
-        });
+}
+async function routeKeysChecksum(routeKeys) {
+    const checksum = new RouteKeysChecksum();
+    for (const routeKeyValue of routeKeys) {
+        await checksum.add(routeKeyValue);
     }
-    async emit(event) {
-        if (!this.options.onEvent)
-            return;
-        await this.options.onEvent(event);
+    return checksum.value();
+}
+function routeKeyForSignedRoute(route) {
+    return `${route.source_id}:${route.destination_id}:${route.chunk_index}`;
+}
+function countDistinctRouteChunks(routes) {
+    return new Set(routes.map((route) => `${route.source_id}:${route.chunk_index}`)).size;
+}
+function countRoutesInChunkPlan(chunks) {
+    return chunks.reduce((sum, chunk) => sum + chunk.destinations.length, 0);
+}
+async function sha256Bytes(value) {
+    const input = new TextEncoder().encode(value);
+    if (globalThis.crypto?.subtle) {
+        return new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", input));
     }
+    const { createHash } = await import("node:crypto");
+    return new Uint8Array(createHash("sha256").update(value).digest());
 }
-function deferredChecksum() {
-    let resolve;
-    let reject;
-    const promise = new Promise((res, rej) => {
-        resolve = res;
-        reject = rej;
-    });
-    return { promise, resolve, reject };
+function hex(bytes) {
+    return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
 }
-export function calculateOptimalChunkSize(totalSize) {
-    const mb = 1024 * 1024;
-    const gb = 1024 * mb;
-    const minChunk = 5 * mb;
-    const maxChunk = 5 * mb;
-    const targetChunks = 10;
-    if (totalSize <= minChunk) {
-        return totalSize;
+async function cancelTransferAfterRouteStreamFailure(client, transferId, cause) {
+    try {
+        await client.cancelTransfer(transferId);
     }
-    if (totalSize < gb) {
-        return Math.max(minChunk, Math.min(maxChunk, Math.floor(totalSize / targetChunks)));
+    catch (cancelError) {
+        throw new Error(`route streaming failed (${errorMessage(cause)}) and transfer cancellation failed (${errorMessage(cancelError)})`);
     }
-    return maxChunk;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
 }
 function newTransferId() {
     const cryptoApi = globalThis.crypto;