@beam-network/sdk 0.5.16 → 0.5.17-dev.1

package/README.md

@@ -166,3 +166,17 @@ 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. 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.
+
+## Hybrid endpoint signing
+
+Credential adapters can use `signDestinationUrl` independently of `signDestinationRoute`, using the same provider configuration and multipart signer. Destination-only signing requires no synthetic source descriptor and reads no source data. Optional `contentMd5` binds the worker-computed checksum to the provider upload without a separate source checksum scan.
+
+`signSourceReadRange` accepts `ifMatch` and `versionId` for frozen S3-compatible sources. Replay the returned headers unchanged. The ETag condition is signed and the version is included in the signed request. Unsupported non-S3 credential modes reject these conditions instead of dropping them. These helpers support the existing S3-compatible profiles used for R2, Hippius S3 and Hugging Face Storage Buckets; Hub repository tokens are a different provider mode.
+
+Only short-lived range/upload routes go to workers. Multipart creation, verification, completion and abort remain in the existing control path. A worker upload response alone is not final-object completion.
+
+`listMultipartParts`, `completeMultipartUpload`, and `inspectDestinationObject` reuse the same provider client and return metadata only. ListParts walks every page; completion submits the selected provider-verified parts. Adapters must durably retain the upload and verified manifest before completion so restart recovery cannot infer delivery from size alone.
+
+Manual releases from `dev` require a committed `-dev.N` version and publish only to npm tag `dev`; the stable tag is unchanged.
+
+Multipart control helpers (`createMultipartUpload`, `listMultipartParts`, `completeMultipartUpload`, `inspectDestinationObject`, and `abortMultipartUpload`) accept an optional `AbortSignal` and cancel through the existing provider HTTP transport. Pass it as `signal` in object arguments or as the last positional argument. Cancellation stops waiting and network activity; it cannot undo a provider operation already accepted. After an interrupted completion, inspect the durable upload/object identity before retrying or reporting cleanup complete.

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./client.js";
 export * from "./models.js";
 export * from "./provider-signing.js";
+export * from "./multipart-limits.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export * from "./client.js";
 export * from "./models.js";
 export * from "./provider-signing.js";
+export * from "./multipart-limits.js";

package/dist/provider-signing.d.ts

@@ -18,6 +18,7 @@ export declare function createMultipartUpload(input: {
     destination: ProviderDestinationConfig;
     objectKey: string;
     metadata: Record<string, string>;
+    signal?: AbortSignal;
 }): Promise<string>;
 export declare function signFinalObjectHead(destination: ProviderDestinationConfig, objectKey: string, expiresIn: number): Promise<string>;
 export declare function signCompleteMultipartUpload(destination: ProviderDestinationConfig, objectKey: string, uploadId: string, expiresIn: number): Promise<string>;
@@ -26,7 +27,32 @@ export declare function signListMultipartUpload(destination: ProviderDestination
     maxParts?: number;
     partNumberMarker?: number;
 }): Promise<string>;
-export declare function abortMultipartUpload(destination: ProviderDestinationConfig, objectKey: string, uploadId: string): Promise<void>;
+export declare function abortMultipartUpload(destination: ProviderDestinationConfig, objectKey: string, uploadId: string, signal?: AbortSignal): Promise<void>;
+/** Provider metadata only. These operations never read or proxy object bytes. */
+export declare function listMultipartParts(destination: ProviderDestinationConfig, objectKey: string, uploadId: string, signal?: AbortSignal): Promise<{
+    partNumber: number;
+    etag: string;
+    size: number;
+}[]>;
+export declare function completeMultipartUpload(input: {
+    destination: ProviderDestinationConfig;
+    objectKey: string;
+    uploadId: string;
+    parts: {
+        partNumber: number;
+        etag: string;
+    }[];
+    signal?: AbortSignal;
+}): Promise<{
+    etag: string | undefined;
+    versionId: string | undefined;
+}>;
+export declare function inspectDestinationObject(destination: ProviderDestinationConfig, objectKey: string, signal?: AbortSignal): Promise<{
+    size: number | undefined;
+    etag: string | undefined;
+    versionId: string | undefined;
+    metadata: Record<string, string>;
+}>;
 export declare function signDestinationRoute(input: {
     chunk: ChunkSigningPlanItem;
     target: ChunkDestinationSigningTarget;
@@ -51,6 +77,8 @@ export declare function signDestinationRoute(input: {
 }): Promise<SignedChunkRoute>;
 export declare function signSourceReadRange(input: {
     source: ProviderSourceConfig;
+    ifMatch?: string;
+    versionId?: string;
     offset: number;
     length: number;
     expiresIn: number;
@@ -70,6 +98,15 @@ export declare function signDestinationReadRange(input: {
     url: string;
     headers: Record<string, string>;
 }>;
+export declare function signDestinationUrl(input: {
+    contentMd5?: string;
+    destination: ProviderDestinationConfig;
+    objectKey: string;
+    uploadId?: string;
+    partNumber?: number;
+    expiresIn: number;
+    fetchImpl?: typeof fetch;
+}): Promise<string>;
 export declare function isS3CompatibleProvider(config: ProviderSourceConfig | ProviderDestinationConfig): config is AnyS3CompatibleProviderConfig;
 export declare function s3CompatibleEndpoint(source: AnyS3CompatibleProviderConfig): string | undefined;
 export declare function s3CompatibleRegion(source: AnyS3CompatibleProviderConfig): string;

package/dist/provider-signing.js

@@ -152,7 +152,7 @@ export async function createMultipartUpload(input) {
             Bucket: input.destination.bucket,
             Key: input.objectKey,
             Metadata: input.metadata
-        }));
+        }), { abortSignal: input.signal });
         if (!response.UploadId) {
             throw new Error(`provider did not return UploadId for ${input.objectKey}`);
         }
@@ -194,13 +194,51 @@ export async function signListMultipartUpload(destination, objectKey, uploadId,
     }
     throw new Error(`multipart list-parts is not supported for ${destination.provider}`);
 }
-export async function abortMultipartUpload(destination, objectKey, uploadId) {
+export async function abortMultipartUpload(destination, objectKey, uploadId, signal) {
     if (isS3CompatibleProvider(destination)) {
-        await createS3CompatibleClient(destination).send(new AbortMultipartUploadCommand({ Bucket: destination.bucket, Key: objectKey, UploadId: uploadId }));
+        await createS3CompatibleClient(destination).send(new AbortMultipartUploadCommand({ Bucket: destination.bucket, Key: objectKey, UploadId: uploadId }), { abortSignal: signal });
         return;
     }
     throw new Error(`multipart abort is not supported for ${destination.provider}`);
 }
+/** Provider metadata only. These operations never read or proxy object bytes. */
+export async function listMultipartParts(destination, objectKey, uploadId, signal) {
+    if (!isS3CompatibleProvider(destination))
+        return unsupportedProviderConfig(destination);
+    const parts = [];
+    let marker;
+    do {
+        const page = await createS3CompatibleClient(destination).send(new ListPartsCommand({
+            Bucket: destination.bucket, Key: objectKey, UploadId: uploadId, MaxParts: 1000, PartNumberMarker: marker
+        }), { abortSignal: signal });
+        for (const part of page.Parts ?? []) {
+            if (!part.PartNumber || !part.ETag || !Number.isSafeInteger(part.Size))
+                throw new Error("invalid multipart part metadata");
+            parts.push({ partNumber: part.PartNumber, etag: part.ETag, size: part.Size });
+        }
+        const next = page.IsTruncated ? page.NextPartNumberMarker : undefined;
+        if (page.IsTruncated && (!next || next === marker))
+            throw new Error("invalid multipart pagination");
+        marker = next;
+    } while (marker);
+    return parts;
+}
+export async function completeMultipartUpload(input) {
+    if (!isS3CompatibleProvider(input.destination))
+        return unsupportedProviderConfig(input.destination);
+    const result = await createS3CompatibleClient(input.destination).send(new CompleteMultipartUploadCommand({
+        Bucket: input.destination.bucket, Key: input.objectKey, UploadId: input.uploadId,
+        MultipartUpload: { Parts: [...input.parts].sort((a, b) => a.partNumber - b.partNumber)
+                .map((part) => ({ PartNumber: part.partNumber, ETag: part.etag })) }
+    }), { abortSignal: input.signal });
+    return { etag: result.ETag, versionId: result.VersionId };
+}
+export async function inspectDestinationObject(destination, objectKey, signal) {
+    if (!isS3CompatibleProvider(destination))
+        return unsupportedProviderConfig(destination);
+    const result = await createS3CompatibleClient(destination).send(new HeadObjectCommand({ Bucket: destination.bucket, Key: objectKey }), { abortSignal: signal });
+    return { size: result.ContentLength, etag: result.ETag, versionId: result.VersionId, metadata: result.Metadata ?? {} };
+}
 export async function signDestinationRoute(input) {
     const targetObjectKey = input.target.object_key;
     if (!targetObjectKey) {
@@ -266,11 +304,15 @@ export async function signSourceReadRange(input) {
             url: await getSignedUrl(client, new GetObjectCommand({
                 Bucket: input.source.bucket,
                 Key: input.source.key,
-                Range: range
+                Range: range,
+                IfMatch: input.ifMatch,
+                VersionId: input.versionId
             }), { expiresIn: input.expiresIn }),
-            headers: { Range: range }
+            headers: { Range: range, ...(input.ifMatch ? { "If-Match": input.ifMatch } : {}) }
         };
     }
+    if (input.ifMatch || input.versionId)
+        throw new Error("conditional source ranges require S3-compatible storage");
     if (isHippiusProvider(input.source)) {
         return {
             url: await hippiusPresign(input.fetchImpl ?? globalThis.fetch, input.source.base_url ?? "https://api.hippius.com", input.source.api_token, input.source.bucket, input.source.key, "get", input.expiresIn),
@@ -341,7 +383,7 @@ async function signSourceRoute(input) {
     }
     return unsupportedProviderConfig(input.source);
 }
-async function signDestinationUrl(input) {
+export async function signDestinationUrl(input) {
     if (isS3CompatibleProvider(input.destination)) {
         const client = createS3CompatibleClient(input.destination);
         if (input.uploadId && input.partNumber) {
@@ -349,11 +391,14 @@ async function signDestinationUrl(input) {
                 Bucket: input.destination.bucket,
                 Key: input.objectKey,
                 UploadId: input.uploadId,
-                PartNumber: input.partNumber
+                PartNumber: input.partNumber,
+                ContentMD5: input.contentMd5
             }), { expiresIn: input.expiresIn });
         }
-        return getSignedUrl(client, new PutObjectCommand({ Bucket: input.destination.bucket, Key: input.objectKey }), { expiresIn: input.expiresIn });
+        return getSignedUrl(client, new PutObjectCommand({ Bucket: input.destination.bucket, Key: input.objectKey, ContentMD5: input.contentMd5 }), { expiresIn: input.expiresIn });
     }
+    if (input.contentMd5)
+        throw new Error("checksum-bound uploads require S3-compatible storage");
     if (isHippiusProvider(input.destination)) {
         return hippiusPresign(input.fetchImpl ?? globalThis.fetch, input.destination.base_url ?? "https://api.hippius.com", input.destination.api_token, input.destination.bucket, input.objectKey, "put", input.expiresIn);
     }

package/package.json

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