@beam-network/sdk 0.5.13 → 0.5.14

package/README.md

@@ -110,4 +110,4 @@ NATS requires this guard because the broker rejects messages above its configure
 
 ## Restart Recovery
 
-The client keeps one in-memory recovery lease per active transfer and one `runtime.hello` monitor per active shard. The lease is installed before route-stream begin, and a per-transfer lock coalesces initial streaming with replay. Multipart recovery retains the existing upload IDs and compact group state, then re-signs only the expiring route and commit controls. A Runtime epoch change invalidates cached auth, coalesces one `transfer.resume`, and regenerates routes under a fresh generation; a transport-only epoch change replays only when Runtime reports routes missing or expired. Provider credentials and signing inputs are retained only in memory and released on terminal status or `close()`. Low-level `attachSignedUrls` requires `routeGenerationId`, the plan fingerprint/checksum, and a `recoveryFactory`; signed URLs are never journaled to disk. Foreground cancellation, deadline expiry, and Runtime state-loss responses keep the background lease and retained multipart upload alive.
+The client keeps one in-memory recovery lease per active transfer and one `runtime.hello` monitor per active shard. The lease is installed before route-stream begin, and a per-transfer lock coalesces initial streaming with replay. Multipart recovery retains the existing upload IDs and compact group state, then re-signs only the expiring route and commit controls. Each `resumeProviderTransfer` invocation re-prepares an existing transfer by explicit transfer id with a fresh request and route generation, while transport retries within that invocation reuse the same request. It then reattaches route-recovery signing from the current provider configs without creating duplicate multipart uploads. A Runtime epoch change invalidates cached auth, coalesces one `transfer.resume`, and regenerates routes under a fresh generation; a transport-only epoch change replays only when Runtime reports routes missing or expired. Provider credentials and signing inputs are retained only in memory and released on terminal status or `close()`. Low-level `attachSignedUrls` requires `routeGenerationId`, the plan fingerprint/checksum, and a `recoveryFactory`; signed URLs are never journaled to disk. Foreground cancellation, deadline expiry, and Runtime state-loss responses keep the background lease and retained multipart upload alive.

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AttachSignedUrlsResponse, BeamClientOptions, DistributeResponse, MultipartGroupManifest, PlanningHttpSource, PreparedDestination, PreparedHttpSource, ProviderTransferCreateInput, RawTransferCreateInput, SignedChunkRoute, SignedUrlFlow, TransferCancelResponse, TransferCreateResponse, TransferPlanResponse, TransferPrepareResponse, TransferStatusInfo, TransferTerminalSignalWaiter } from "./models.js";
+import type { AttachSignedUrlsResponse, BeamClientOptions, DistributeResponse, MultipartGroupManifest, PlanningHttpSource, PreparedDestination, PreparedHttpSource, ProviderTransferCreateInput, ProviderTransferResumeInput, RawTransferCreateInput, SignedChunkRoute, SignedUrlFlow, TransferCancelResponse, TransferCreateResponse, TransferPlanResponse, TransferPrepareResponse, TransferStatusInfo, TransferTerminalSignalWaiter } from "./models.js";
 import { BEAM_DEFAULT_NATS_URL } from "./nats-control.js";
 export declare class BeamRouteRecoveryPendingError extends Error {
     readonly transferId: string;
@@ -24,6 +24,17 @@ export declare class BeamApiError extends Error {
     readonly body: string;
     constructor(message: string, status: number, body: string);
 }
+type TransferPrepareInput = {
+    transferId?: string;
+    sources: PreparedHttpSource[];
+    destinations: PreparedDestination[];
+    name?: string;
+    testMode?: boolean;
+    urlsExpiresAt?: string;
+    signedUrlFlow?: SignedUrlFlow;
+    idempotencyKey?: string;
+    routeGenerationId?: string;
+};
 export declare class BeamClient {
     readonly apiKey: string;
     readonly natsUrl: string;
@@ -40,6 +51,7 @@ export declare class BeamClient {
     openTransferTerminalWaiter(transferId: string): Promise<TransferTerminalSignalWaiter>;
     createRawTransfer(input: RawTransferCreateInput): Promise<TransferCreateResponse>;
     createTransfer(input: ProviderTransferCreateInput): Promise<TransferPrepareResponse>;
+    resumeProviderTransfer(input: ProviderTransferResumeInput): Promise<TransferPrepareResponse>;
     transferStatus(transferId: string): Promise<TransferStatusInfo>;
     distributeTransfer(transferId: string): Promise<DistributeResponse>;
     cancelTransfer(transferId: string): Promise<TransferCancelResponse>;
@@ -51,16 +63,8 @@ export declare class BeamClient {
         urlsExpiresAt?: string;
         signedUrlFlow?: SignedUrlFlow;
     }): Promise<TransferPlanResponse>;
-    prepareTransfer(input: {
-        sources: PreparedHttpSource[];
-        destinations: PreparedDestination[];
-        name?: string;
-        testMode?: boolean;
-        urlsExpiresAt?: string;
-        signedUrlFlow?: SignedUrlFlow;
-        idempotencyKey?: string;
-        routeGenerationId?: string;
-    }): Promise<TransferPrepareResponse>;
+    prepareTransfer(input: TransferPrepareInput): Promise<TransferPrepareResponse>;
+    private prepareTransferWithRequestKey;
     attachSignedUrls(transferId: string, input: {
         chunkRoutes: SignedChunkRoute[];
         multipartGroupManifest: MultipartGroupManifest[];
@@ -79,6 +83,7 @@ export declare class BeamClient {
     prepareProviderTransfer(input: ProviderTransferCreateInput): Promise<TransferPrepareResponse>;
     private signProviderRoute;
     private startProviderRouteRecoverySigner;
+    private recoveryMultipartUploadState;
     private submitIntegrityAuditGrantsIfPresent;
     private submitProviderIntegrityAuditGrants;
     private stopRecoverySigner;

package/dist/client.js

@@ -111,6 +111,65 @@ export class BeamClient {
     createTransfer(input) {
         return this.prepareProviderTransfer(input);
     }
+    async resumeProviderTransfer(input) {
+        validateId(input.transferId, "transferId");
+        const expiresIn = input.expiresIn ?? 3600;
+        const requestedSignedUrlFlow = input.signedUrlFlow ?? "signed_url";
+        const retainedRecoveryInput = {
+            ...input,
+            sources: input.sources.map((source) => ({ ...source })),
+            destinations: input.destinations.map((destination) => ({ ...destination }))
+        };
+        const preparedDestinations = retainedRecoveryInput.destinations.map((destination, index) => prepareProviderDestination(destination, { index }));
+        const destinationsById = new Map();
+        preparedDestinations.forEach((preparedDestination, index) => {
+            const destination = retainedRecoveryInput.destinations[index];
+            if (!destination) {
+                throw new Error(`missing provider destination config for prepared destination ${preparedDestination.destination_id}`);
+            }
+            destinationsById.set(preparedDestination.destination_id, destination);
+        });
+        const preparedSources = await Promise.all(retainedRecoveryInput.sources.map((source, index) => prepareProviderSource(source, { index, expiresIn, fetchImpl: this.fetchImpl })));
+        const resumePrepareRequestKey = `transfer:${input.transferId}:prepare:resume:${randomUuid()}`;
+        const prepared = await this.prepareTransferWithRequestKey({
+            transferId: input.transferId,
+            sources: preparedSources,
+            destinations: preparedDestinations,
+            name: input.name,
+            testMode: input.testMode,
+            signedUrlFlow: requestedSignedUrlFlow
+        }, resumePrepareRequestKey);
+        if (!prepared.success)
+            return prepared;
+        if (prepared.transfer_id !== input.transferId) {
+            throw new Error("resumed provider transfer id mismatch");
+        }
+        const sourcesById = new Map();
+        preparedSources.forEach((preparedSource, index) => {
+            const source = retainedRecoveryInput.sources[index];
+            if (!source) {
+                throw new Error(`missing provider source config for prepared source ${preparedSource.source_id}`);
+            }
+            sourcesById.set(preparedSource.source_id, source);
+        });
+        await this.startProviderRouteRecoverySigner({
+            prepared,
+            sourcesById,
+            destinationsById,
+            multipartUploads: new Map(),
+            expiresIn
+        });
+        this.control.registerRecoveryLease({
+            transferId: prepared.transfer_id,
+            planFingerprint: prepared.plan_fingerprint,
+            coordinateChecksum: prepared.coordinate_checksum,
+            replayRoutes: async () => {
+                throw new Error("route replay is unavailable after provider action resume; route signing remains available");
+            },
+            disposeSecrets: () => clearProviderResumeSecrets(retainedRecoveryInput)
+        });
+        return prepared;
+    }
     async transferStatus(transferId) {
         validateId(transferId, "transferId");
         const status = await this.control.request("transfer.status", { transfer_id: transferId }, { transferId });
@@ -151,9 +210,13 @@ export class BeamClient {
             validateCompactTransferPlan(result.plan_descriptor, result.signed_url_flow);
         return result;
     }
-    async prepareTransfer(input) {
-        const transferId = await transferIdForIdempotencyKey(input.idempotencyKey);
-        const prepareIdempotencyKey = `transfer:${transferId}:prepare`;
+    prepareTransfer(input) {
+        return this.prepareTransferWithRequestKey(input);
+    }
+    async prepareTransferWithRequestKey(input, requestKey) {
+        const transferId = input.transferId ?? await transferIdForIdempotencyKey(input.idempotencyKey);
+        validateId(transferId, "transferId");
+        const prepareIdempotencyKey = requestKey ?? `transfer:${transferId}:prepare`;
         const routeGenerationId = input.routeGenerationId ?? await routeGenerationIdForPrepareIdempotencyKey(prepareIdempotencyKey);
         const result = await this.control.request("transfer.prepare", compact({
             transfer_id: transferId,
@@ -548,15 +611,15 @@ export class BeamClient {
                 const destination = input.destinationsById.get(requested.destination_id);
                 if (!source || !destination)
                     throw new Error("route recovery provider configuration is unavailable");
-                const upload = input.multipartUploads.get(requested.multipart_group_id);
-                if (!upload)
-                    throw new Error(`route recovery multipart upload is unavailable: ${requested.multipart_group_id}`);
-                if (upload.uploadId !== requested.upload_id
-                    || upload.objectKey !== requested.final_object_key
-                    || upload.manifest.source_id !== requested.source_id
-                    || upload.manifest.destination_id !== requested.destination_id) {
-                    throw new Error("route recovery multipart identity mismatch");
-                }
+                const upload = isHippiusDestination(destination)
+                    ? undefined
+                    : await this.recoveryMultipartUploadState({
+                        prepared: input.prepared,
+                        destination,
+                        requested,
+                        multipartUploads: input.multipartUploads,
+                        expiresIn: input.expiresIn
+                    });
                 return this.signProviderRoute({
                     chunk,
                     target: {
@@ -579,7 +642,7 @@ export class BeamClient {
                     source,
                     destination,
                     expiresIn: input.expiresIn,
-                    upload,
+                    ...(upload ? { upload } : {}),
                     transferId: input.prepared.transfer_id,
                     finalObjectKey: requested.final_object_key,
                     signedUrlFlow: "signed_url",
@@ -604,6 +667,63 @@ export class BeamClient {
             });
         });
     }
+    async recoveryMultipartUploadState(input) {
+        const existing = input.multipartUploads.get(input.requested.multipart_group_id);
+        if (existing) {
+            if (existing.uploadId !== input.requested.upload_id
+                || existing.objectKey !== input.requested.final_object_key
+                || existing.manifest.source_id !== input.requested.source_id
+                || existing.manifest.destination_id !== input.requested.destination_id) {
+                throw new Error("route recovery multipart identity mismatch");
+            }
+            return existing;
+        }
+        if (!input.requested.upload_id) {
+            throw new Error("route recovery multipart upload id is required");
+        }
+        const source = input.prepared.plan_descriptor.sources.find((candidate) => candidate.source_id === input.requested.source_id);
+        if (!source) {
+            throw new Error("route recovery source plan is unavailable");
+        }
+        const expectedGroupId = multipartGroupStateKey(input.prepared.transfer_id, input.requested.destination_id, input.requested.source_id, input.requested.final_object_key);
+        if (input.requested.multipart_group_id !== expectedGroupId) {
+            throw new Error("route recovery multipart group identity mismatch");
+        }
+        const finalObjectMetadata = { "beam-transfer-id": input.prepared.transfer_id };
+        const maxPartNumber = multipartMaxPartNumber(source.chunk_count);
+        const listPageMarkers = multipartListPageMarkers(maxPartNumber);
+        const [completeUrl, abortUrl, listPageUrls, finalHeadUrl] = await Promise.all([
+            signCompleteMultipartUpload(input.destination, input.requested.final_object_key, input.requested.upload_id, input.expiresIn),
+            signAbortMultipartUpload(input.destination, input.requested.final_object_key, input.requested.upload_id, input.expiresIn),
+            Promise.all(listPageMarkers.map((partNumberMarker) => signListMultipartUpload(input.destination, input.requested.final_object_key, input.requested.upload_id, input.expiresIn, { maxParts: 1_000, ...(partNumberMarker ? { partNumberMarker } : {}) }))),
+            signFinalObjectHead(input.destination, input.requested.final_object_key, input.expiresIn)
+        ]);
+        const manifest = {
+            multipart_group_id: input.requested.multipart_group_id,
+            source_id: input.requested.source_id,
+            destination_id: input.requested.destination_id,
+            final_object_key: input.requested.final_object_key,
+            upload_id: input.requested.upload_id,
+            expected_object_size: source.size,
+            expected_part_count: source.chunk_count,
+            max_part_number: maxPartNumber,
+            complete_url: completeUrl,
+            abort_url: abortUrl,
+            list_page_urls: listPageUrls,
+            final_head_url: finalHeadUrl,
+            final_object_metadata: finalObjectMetadata,
+            urls_expires_at: expiresAtIso(input.expiresIn)
+        };
+        validateMultipartGroupManifest([manifest], input.prepared.transfer_id);
+        const state = {
+            destination: input.destination,
+            objectKey: input.requested.final_object_key,
+            uploadId: input.requested.upload_id,
+            manifest
+        };
+        input.multipartUploads.set(input.requested.multipart_group_id, state);
+        return state;
+    }
     async submitIntegrityAuditGrantsIfPresent(status) {
         const challenge = status.integrity_audit_challenge;
         if (!challenge)
@@ -1496,3 +1616,13 @@ function clearRecoverySecrets(input) {
         }
     }
 }
+function clearProviderResumeSecrets(input) {
+    const secretKeys = new Set(["access_key_id", "secret_access_key", "session_token", "api_token", "token", "password"]);
+    for (const provider of [...input.sources, ...input.destinations]) {
+        const record = provider;
+        for (const key of secretKeys) {
+            if (key in record)
+                record[key] = "";
+        }
+    }
+}

package/dist/models.d.ts

@@ -171,6 +171,18 @@ export interface TransferStatusInfo {
     };
     integrity_audit_challenge?: IntegrityAuditChallenge;
 }
+export interface ProviderTransferResumeInput {
+    transferId: string;
+    sources: ProviderSourceConfig[];
+    destinations: ProviderDestinationConfig[];
+    name?: string;
+    /**
+     * Maps to BeamCore test_mode. Must match the original prepared transfer.
+     */
+    testMode?: boolean;
+    expiresIn?: number;
+    signedUrlFlow?: SignedUrlFlow;
+}
 export interface TransferTerminalEvent {
     schema_version: "transfer-client-control/v6";
     producer: "transfer-runtime";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@beam-network/sdk",
-    "version": "0.5.13",
+    "version": "0.5.14",
     "description": "TypeScript SDK for BEAM transfer creation and management.",
     "type": "module",
     "license": "MIT",