@beam-network/sdk 0.6.0 → 0.7.0

package/dist/models.d.ts

@@ -1,5 +1,27 @@
 export type SignedUrlFlow = "signed_url";
+export interface SdkPerformanceSummary {
+    gauges?: Record<string, number>;
+    milestones?: Record<string, number>;
+    unmeasured?: string[];
+    detail_dropped?: number;
+    schema_version: "sdk-performance/v1" | "sdk-performance/v2";
+    measurements: Array<{
+        name: string;
+        count: number;
+        work_ms: number;
+        max_ms: number;
+        histogram?: number[];
+    }>;
+    counters: {
+        source_signatures: number;
+        source_reuses: number;
+        route_batches: number;
+        source_renewals?: number;
+    };
+}
 export interface BeamClientOptions {
+    /** Best effort, at most one bounded summary per route stream. Never awaited. */
+    onDiagnostics?: (summary: SdkPerformanceSummary) => void | Promise<void>;
     apiKey?: string;
     natsUrl?: string;
     natsWsUrl?: string;
@@ -141,7 +163,50 @@ export interface IntegrityAuditChallenge {
     range_bytes: number;
     chunks: IntegrityAuditChallengeChunk[];
 }
+export interface TransferPerformance {
+    recovery_bandwidth?: {
+        excluded_tasks: number;
+        accepted_bytes: number;
+    };
+    deadline?: {
+        version: "assignment-deadline/v1";
+        decisions: number;
+        selected_min_ms: number;
+        selected_max_ms: number;
+        estimated_max_ms: number;
+        sample_count_max: number;
+        data_age_max_ms: number | null;
+        reasons: Record<string, number>;
+    };
+    sdk_detail?: SdkPerformanceSummary;
+    schema_version: "transfer-performance/v1";
+    runtime_epoch: string;
+    coverage: "complete" | "restarted";
+    elapsed_ms: number;
+    /** Work can overlap; these durations must not be summed into elapsed time. */
+    measurements: Record<string, {
+        count: number;
+        work_ms: number;
+        max_ms: number;
+    }>;
+    events: Record<string, {
+        count: number;
+        first_ms: number;
+        last_ms: number;
+    }>;
+    sdk_counters: {
+        source_signatures: number;
+        source_reuses: number;
+        route_batches: number;
+        source_renewals?: number;
+    };
+    detail_dropped: number;
+    unmeasured?: string[];
+    measurement_clocks?: Record<string, "runtime" | "sdk" | "fraud-service">;
+    sdk_report_received?: boolean;
+}
 export interface TransferStatusInfo {
+    performance?: TransferPerformance | null;
     transfer_id: string;
     name?: string;
     status: string;
@@ -190,6 +255,8 @@ export interface TransferTerminalSignalWaiter {
     close(): Promise<void>;
 }
 export interface S3ProviderConfig {
+    /** Physical storage location; independent of the signing region. */
+    storage_location?: string;
     provider: "s3";
     id?: string;
     bucket: string;
@@ -201,6 +268,8 @@ export interface S3ProviderConfig {
     endpoint_url?: string;
 }
 export interface R2ProviderConfig {
+    /** Physical storage location; independent of the signing region. */
+    storage_location?: string;
     provider: "r2";
     id?: string;
     bucket: string;
@@ -211,6 +280,8 @@ export interface R2ProviderConfig {
     endpoint_url?: string;
 }
 export interface S3CompatibleProviderConfig {
+    /** Physical storage location; independent of the signing region. */
+    storage_location?: string;
     provider: string;
     driver?: "s3-compatible";
     id?: string;
@@ -225,6 +296,8 @@ export interface S3CompatibleProviderConfig {
     account_id?: string;
 }
 export interface HippiusProviderConfig {
+    /** Physical storage location; independent of the signing region. */
+    storage_location?: string;
     provider: "hippius";
     id?: string;
     bucket: string;
@@ -234,6 +307,8 @@ export interface HippiusProviderConfig {
 }
 export type HuggingFaceRepoType = "model" | "dataset" | "space" | "kernel" | "bucket";
 export interface HuggingFaceProviderConfig {
+    /** Physical storage location; independent of the signing region. */
+    storage_location?: string;
     provider: "huggingface";
     id?: string;
     /** Namespace and repo or bucket name separated by a slash, for example `org/dataset`. */

package/dist/nats-control.d.ts

@@ -1,3 +1,4 @@
+import type { IntegrityAuditChallenge } from "./models.js";
 import { type ConnectionOptions } from "nats";
 import type { MultipartGroupManifest, SignedChunkRoute, TransferTerminalSignalWaiter } from "./models.js";
 export declare const TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION = "transfer-client-control/v7";
@@ -134,18 +135,28 @@ export declare class BeamTransferControl {
     private readonly recoveryOperations;
     private readonly recoveryRequestedEpoch;
     private readonly runtimeEpochs;
+    private readonly runtimeCapabilities;
     private helloTimer;
     constructor(options: TransferControlOptions);
     close(): Promise<void>;
+    serveIntegritySigner(transferId: string, handler: (challenge: IntegrityAuditChallenge) => Promise<Record<string, unknown>>): Promise<() => void>;
     serveRouteRecoverySigner(transferId: string, handler: (payload: RouteRecoverySignRequestPayload) => Promise<RouteRecoverySignReplyPayload>): Promise<() => void>;
     registerRecoveryLease(lease: TransferRecoveryLease): () => void;
-    releaseRecoveryLease(transferId: string): void;
-    continueRecoveryLease(transferId: string): void;
+    /**
+     * Release a transfer's recovery lease, disposing its retained secrets.
+     *
+     * With `owner`, release only when that exact lease is still registered, so a
+     * fenced-off owner can never release a replacement owner's lease.
+     */
+    releaseRecoveryLease(transferId: string, owner?: TransferRecoveryLease): void;
+    /** Request recovery for the registered lease; with `owner`, only if that lease is still registered. */
+    continueRecoveryLease(transferId: string, owner?: TransferRecoveryLease): void;
     request<T>(messageType: TransferClientMessageType, payload: Record<string, unknown>, options?: LifecycleRequestOptions): Promise<T>;
     openTerminalSignalWaiter(transferId: string): Promise<TransferTerminalSignalWaiter>;
     splitRoutesForPayload(messageType: TransferClientMessageType, basePayload: Record<string, unknown>, routes: SignedChunkRoute[]): SignedChunkRoute[][];
     private connection;
     private ensureHelloMonitor;
+    supportsPerformanceV2(transferId: string): boolean;
     private pollRuntimeHello;
     private observeRuntimeEpoch;
     private recoverLease;

package/dist/nats-control.js

@@ -1,3 +1,4 @@
+import { currentSdkPerformance } from "./performance.js";
 import { encode, decode } from "@msgpack/msgpack";
 import { connect } from "nats";
 export const TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION = "transfer-client-control/v7";
@@ -60,9 +61,12 @@ export class BeamTransferControl {
     terminalWaitCancellations = new Set();
     routeRecoverySignerCancellations = new Set();
     recoveryLeases = new Map();
+    // Keyed by lease identity: a replacement owner's recovery must never be
+    // coalesced into (and silently dropped behind) a fenced-off owner's loop.
     recoveryOperations = new Map();
     recoveryRequestedEpoch = new Map();
     runtimeEpochs = new Map();
+    runtimeCapabilities = new Map();
     helloTimer = null;
     constructor(options) {
         this.apiKey = options.apiKey;
@@ -106,6 +110,58 @@ export class BeamTransferControl {
         if (nc && !nc.isClosed())
             await nc.drain();
     }
+    async serveIntegritySigner(transferId, handler) {
+        const nc = await this.connection();
+        const subject = this.routeRecoverySignSubject(transferId).replace(/route_recovery_sign$/, "integrity_sign");
+        let active = true;
+        let pending = null;
+        let auditId = "";
+        let challengeFingerprint = "";
+        let awaiting = 0;
+        const subscription = nc.subscribe(subject, { callback: (error, message) => {
+                if (!active || error || !message.reply)
+                    return;
+                if (awaiting >= 32) {
+                    message.respond(new TextEncoder().encode('{"retry":true}'));
+                    return;
+                }
+                awaiting++;
+                void (async () => {
+                    try {
+                        const request = JSON.parse(new TextDecoder().decode(message.data));
+                        if (request.schema_version !== TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION || request.capability !== "integrity-signing/v1"
+                            || request.producer !== "transfer-runtime" || request.environment !== this.environment || request.key_prefix !== this.keyPrefix
+                            || request.transfer_id !== transferId || request.challenge?.transfer_id !== transferId || typeof request.request_id !== "string")
+                            throw new Error("integrity_sign_scope_mismatch");
+                        const fingerprint = JSON.stringify(request.challenge);
+                        if (pending && (auditId !== request.challenge.audit_id || challengeFingerprint !== fingerprint))
+                            throw new Error("integrity_sign_conflicting_audit");
+                        if (!pending) {
+                            auditId = request.challenge.audit_id;
+                            challengeFingerprint = fingerprint;
+                            pending = handler(request.challenge).finally(() => { pending = null; });
+                        }
+                        const payload = await pending;
+                        if (active)
+                            message.respond(new TextEncoder().encode(JSON.stringify({ schema_version: TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION,
+                                capability: "integrity-signing/v1", environment: this.environment, key_prefix: this.keyPrefix,
+                                transfer_id: transferId, request_id: request.request_id, payload })));
+                    }
+                    catch {
+                        message.respond(new TextEncoder().encode('{"retry":true}'));
+                    }
+                    finally {
+                        awaiting--;
+                    }
+                })();
+            } });
+        await nc.flush();
+        const stop = () => { if (!active)
+            return; active = false; subscription.unsubscribe(); this.routeRecoverySignerCancellations.delete(stop); };
+        this.routeRecoverySignerCancellations.add(stop);
+        void this.pollRuntimeHello(transferShardId(transferId, this.shardCount));
+        return stop;
+    }
     async serveRouteRecoverySigner(transferId, handler) {
         const nc = await this.connection();
         const subject = this.routeRecoverySignSubject(transferId);
@@ -165,23 +221,20 @@ export class BeamTransferControl {
         this.ensureHelloMonitor();
         const shardId = transferShardId(lease.transferId, this.shardCount);
         void this.pollRuntimeHello(shardId);
-        return () => {
-            const current = this.recoveryLeases.get(lease.transferId);
-            if (current !== lease)
-                return;
-            this.recoveryLeases.delete(lease.transferId);
-            this.recoveryRequestedEpoch.delete(lease.transferId);
-            lease.disposeSecrets?.();
-            if (!this.recoveryLeases.size && this.helloTimer) {
-                clearInterval(this.helloTimer);
-                this.helloTimer = null;
-            }
-        };
+        return () => this.releaseRecoveryLease(lease.transferId, lease);
     }
-    releaseRecoveryLease(transferId) {
+    /**
+     * Release a transfer's recovery lease, disposing its retained secrets.
+     *
+     * With `owner`, release only when that exact lease is still registered, so a
+     * fenced-off owner can never release a replacement owner's lease.
+     */
+    releaseRecoveryLease(transferId, owner) {
         const lease = this.recoveryLeases.get(transferId);
         if (!lease)
             return;
+        if (owner && lease !== owner)
+            return;
         this.recoveryLeases.delete(transferId);
         this.recoveryRequestedEpoch.delete(transferId);
         lease.disposeSecrets?.();
@@ -190,10 +243,13 @@ export class BeamTransferControl {
             this.helloTimer = null;
         }
     }
-    continueRecoveryLease(transferId) {
+    /** Request recovery for the registered lease; with `owner`, only if that lease is still registered. */
+    continueRecoveryLease(transferId, owner) {
         const lease = this.recoveryLeases.get(transferId);
         if (!lease || this.closed)
             return;
+        if (owner && lease !== owner)
+            return;
         const shardId = transferShardId(transferId, this.shardCount);
         const epoch = this.runtimeEpochs.get(shardId);
         this.recoveryRequestedEpoch.set(transferId, epoch ? `${epoch.runtimeEpoch}:${epoch.transportEpoch}` : `foreground:${randomId()}`);
@@ -223,7 +279,12 @@ export class BeamTransferControl {
                     producer: "sdk",
                     payload
                 };
+                const encodeStarted = performance.now();
                 const bytes = encode(envelope);
+                if (messageType === "transfer.route_stream.batch") {
+                    currentSdkPerformance()?.observe("sdk.batch_encode", performance.now() - encodeStarted);
+                    currentSdkPerformance()?.gauge("batch_bytes_max", bytes.byteLength);
+                }
                 if (bytes.byteLength > this.maxPayloadBytes) {
                     throw new Error(`NATS lifecycle request is ${bytes.byteLength} bytes, above maxPayloadBytes=${this.maxPayloadBytes}`);
                 }
@@ -434,9 +495,19 @@ export class BeamTransferControl {
         }, 5_000);
         this.helloTimer.unref?.();
     }
+    supportsPerformanceV2(transferId) {
+        const value = this.runtimeCapabilities.get(transferShardId(transferId, this.shardCount));
+        return !!value && value.until > Date.now() && value.capabilities.includes("sdk-performance/v2");
+    }
     async pollRuntimeHello(shardId) {
         try {
-            await this.request("runtime.hello", {}, { idempotencyKey: `runtime:hello:${shardId}`, shardId });
+            try {
+                const hello = await this.request("runtime.hello", { capabilities: ["integrity-signing/v1", "sdk-performance/v2"] }, { idempotencyKey: `runtime:hello:${shardId}:integrity-signing`, shardId });
+                this.runtimeCapabilities.set(shardId, { until: Date.now() + 15_000, capabilities: hello.capabilities ?? [] });
+            }
+            catch {
+                await this.request("runtime.hello", {}, { idempotencyKey: `runtime:hello:${shardId}`, shardId });
+            }
         }
         catch {
             // Infinite NATS reconnect continues in the background; the next hello reconciles epochs.
@@ -451,6 +522,7 @@ export class BeamTransferControl {
             return;
         if (previous.runtimeEpoch === runtimeEpoch && previous.transportEpoch === transportEpoch)
             return;
+        this.runtimeCapabilities.delete(shardId);
         if (previous.runtimeEpoch !== runtimeEpoch) {
             this.authToken = null;
             this.authTokenExpiresAt = 0;
@@ -463,13 +535,14 @@ export class BeamTransferControl {
         }
     }
     recoverLease(lease) {
-        const existing = this.recoveryOperations.get(lease.transferId);
+        const existing = this.recoveryOperations.get(lease);
         if (existing)
             return existing;
-        let operation;
-        operation = (async () => {
+        const owns = () => !this.closed && this.recoveryLeases.get(lease.transferId) === lease;
+        let replaced = false;
+        const operation = (async () => {
             let attempt = 0;
-            while (!this.closed && this.recoveryLeases.get(lease.transferId) === lease) {
+            while (owns()) {
                 const requestedEpoch = this.recoveryRequestedEpoch.get(lease.transferId);
                 const routeGenerationId = randomId();
                 try {
@@ -479,39 +552,53 @@ export class BeamTransferControl {
                         coordinate_checksum: lease.coordinateChecksum,
                         route_generation_id: routeGenerationId
                     }, { transferId: lease.transferId, idempotencyKey: `transfer:${lease.transferId}:resume:${routeGenerationId}` });
+                    if (!owns()) {
+                        // A fenced-off owner must neither act on nor release a replacement's lease.
+                        replaced = true;
+                        return;
+                    }
                     if (response.recovery === "terminal") {
-                        this.releaseRecoveryLease(lease.transferId);
-                        if (this.recoveryOperations.get(lease.transferId) === operation) {
-                            this.recoveryOperations.delete(lease.transferId);
-                        }
+                        this.releaseRecoveryLease(lease.transferId, lease);
                         return;
                     }
                     if (response.route_replay_required || response.recovery === "route_replay_required") {
                         await lease.replayRoutes(routeGenerationId);
+                        if (!owns()) {
+                            replaced = true;
+                            return;
+                        }
                     }
                     if (this.recoveryRequestedEpoch.get(lease.transferId) !== requestedEpoch) {
                         attempt = 0;
                         continue;
                     }
-                    if (this.recoveryOperations.get(lease.transferId) === operation) {
-                        this.recoveryOperations.delete(lease.transferId);
-                    }
                     return;
                 }
                 catch (error) {
+                    if (!owns()) {
+                        replaced = true;
+                        return;
+                    }
                     if (!isRetryableLifecycleError(error)) {
-                        this.releaseRecoveryLease(lease.transferId);
+                        this.releaseRecoveryLease(lease.transferId, lease);
                         return;
                     }
                     attempt += 1;
                     await sleepWithJitter(Math.min(30_000, 500 * (2 ** Math.min(attempt, 6))));
                 }
             }
+            replaced = !this.closed;
         })().finally(() => {
-            if (this.recoveryOperations.get(lease.transferId) === operation)
-                this.recoveryOperations.delete(lease.transferId);
+            if (this.recoveryOperations.get(lease) === operation)
+                this.recoveryOperations.delete(lease);
+            if (!replaced || this.closed)
+                return;
+            // The recovery this loop was driving still matters: hand it to the replacement owner.
+            const current = this.recoveryLeases.get(lease.transferId);
+            if (current && current !== lease)
+                void this.recoverLease(current);
         });
-        this.recoveryOperations.set(lease.transferId, operation);
+        this.recoveryOperations.set(lease, operation);
         return operation;
     }
     async resolveAuthToken() {

package/dist/performance.d.ts

@@ -0,0 +1,39 @@
+import type { SdkPerformanceSummary } from './models.js';
+export declare const currentSdkPerformance: () => SdkPerformanceCollector | undefined;
+export declare const measureSdkPhase: <T>(name: string, work: () => Promise<T>) => Promise<T>;
+/** Bounded identities only: no URLs, credentials or grant bodies. */
+export declare class SourceSignatureHistory {
+    complete: boolean;
+    private readonly bits;
+    constructor(complete?: boolean);
+    created(index: number): boolean;
+}
+export declare class SdkPerformanceCollector {
+    private readonly sourceHistory?;
+    constructor(sourceHistory?: SourceSignatureHistory | undefined);
+    private sourceRenewals;
+    sourceCreated(index: number): void;
+    private readonly started;
+    private readonly details;
+    private readonly cpu;
+    private finished;
+    private delayTimer?;
+    private readonly measurements;
+    private readonly gauges;
+    private readonly milestones;
+    private dropped;
+    readonly counters: {
+        source_signatures: number;
+        source_reuses: number;
+        route_batches: number;
+    };
+    observe(name: string, milliseconds: number): void;
+    gauge(name: string, value: number): void;
+    increment(name: string): void;
+    seedDiscovery(other: SdkPerformanceCollector): void;
+    mark(name: string): void;
+    measure<T>(name: string, work: () => Promise<T>): Promise<T>;
+    startDelaySampling(): void;
+    finish(): void;
+    snapshot(v2?: boolean): SdkPerformanceSummary;
+}

package/dist/performance.js

@@ -0,0 +1,124 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const NAMES = ["sdk.discovery", "sdk.multipart_create", "sdk.signing", "sdk.batch_ack", "sdk.buffer_wait", "sdk.preparation", "sdk.source_signing", "sdk.destination_signing", "sdk.source_grant_wait", "sdk.multipart_ready_wait", "sdk.multipart_provider", "sdk.multipart_queue", "sdk.multipart_callback", "sdk.manifest_ack", "sdk.provider_client_setup", "sdk.metadata_request", "sdk.route_assembly", "sdk.batch_encode", "sdk.batch_checksum", "sdk.batch_queue", "sdk.signing_queue", "sdk.process_cpu", "sdk.event_loop_delay", "sdk.producer_wait"];
+const BOUNDS = [0.1, .5, 1, 2, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000, 30000, 120000];
+const GAUGES = new Set(["signing_configured_limit", "multipart_configured_limit", "signing_limit", "multipart_limit", "signing_active_peak", "signing_pending_peak", "multipart_active_peak", "buffered_batches_peak", "batch_routes_max", "batch_bytes_max", "concurrency_changes", "source_waiters", "provider_clients_created", "provider_clients_reused"]);
+const MILESTONES = new Set(["first_manifest_ms", "first_route_ms", "first_batch_ms", "final_flush_ms", "prepared_ms"]);
+const context = new AsyncLocalStorage();
+let activeDelaySamplers = 0;
+export const currentSdkPerformance = () => context.getStore();
+export const measureSdkPhase = (name, work) => context.getStore()?.measure(name, work) ?? work();
+/** Bounded identities only: no URLs, credentials or grant bodies. */
+export class SourceSignatureHistory {
+    complete;
+    bits = new Uint8Array(16_384);
+    constructor(complete = true) {
+        this.complete = complete;
+    }
+    created(index) {
+        if (!Number.isSafeInteger(index) || index < 0 || index >= this.bits.length * 8) {
+            this.complete = false;
+            return false;
+        }
+        const byte = index >>> 3, mask = 1 << (index & 7);
+        const renewed = (this.bits[byte] & mask) !== 0;
+        this.bits[byte] |= mask;
+        return renewed;
+    }
+}
+export class SdkPerformanceCollector {
+    sourceHistory;
+    constructor(sourceHistory) {
+        this.sourceHistory = sourceHistory;
+    }
+    sourceRenewals = 0;
+    sourceCreated(index) {
+        this.counters.source_signatures++;
+        if (this.sourceHistory?.created(index))
+            this.sourceRenewals++;
+    }
+    started = performance.now();
+    details = process.env.BEAM_SDK_PERFORMANCE_DETAILS !== 'false';
+    cpu = process.cpuUsage();
+    finished = false;
+    delayTimer;
+    measurements = new Map();
+    gauges = {};
+    milestones = {};
+    dropped = 0;
+    counters = { source_signatures: 0, source_reuses: 0, route_batches: 0 };
+    observe(name, milliseconds) {
+        const index = NAMES.indexOf(name);
+        if (index < 0 || (!this.details && index >= 6) || !Number.isFinite(milliseconds) || milliseconds < 0 || milliseconds > 86_400_000)
+            return;
+        const value = this.measurements.get(name) ?? { count: 0, work_ms: 0, max_ms: 0, histogram: Array(18).fill(0) };
+        if (value.count >= 1_000_000 || value.work_ms + milliseconds > 86_400_000) {
+            this.dropped++;
+            return;
+        }
+        value.count++;
+        value.work_ms += milliseconds;
+        value.max_ms = Math.max(value.max_ms, milliseconds);
+        const bin = BOUNDS.findIndex(bound => milliseconds <= bound);
+        value.histogram[bin < 0 ? 17 : bin]++;
+        this.measurements.set(name, value);
+    }
+    gauge(name, value) {
+        if (this.details && GAUGES.has(name) && Number.isFinite(value) && value >= 0)
+            this.gauges[name] = Math.min(1_000_000_000, Math.max(this.gauges[name] ?? 0, value));
+    }
+    increment(name) { this.gauge(name, (this.gauges[name] ?? 0) + 1); }
+    seedDiscovery(other) {
+        for (const name of ["sdk.discovery", "sdk.metadata_request", "sdk.provider_client_setup"]) {
+            const value = other.measurements.get(name);
+            if (value)
+                this.measurements.set(name, { ...value, histogram: [...value.histogram] });
+        }
+        for (const name of ["provider_clients_created", "provider_clients_reused"])
+            if (other.gauges[name] !== undefined)
+                this.gauges[name] = other.gauges[name];
+    }
+    mark(name) {
+        if (this.details && MILESTONES.has(name) && this.milestones[name] === undefined)
+            this.milestones[name] = performance.now() - this.started;
+    }
+    async measure(name, work) {
+        const start = performance.now();
+        try {
+            return await context.run(this, work);
+        }
+        finally {
+            this.observe(name, performance.now() - start);
+        }
+    }
+    startDelaySampling() {
+        if (!this.details || this.delayTimer || this.finished || activeDelaySamplers >= 16)
+            return;
+        activeDelaySamplers++;
+        let last = performance.now();
+        this.delayTimer = setInterval(() => {
+            const now = performance.now();
+            this.observe('sdk.event_loop_delay', Math.max(0, now - last - 100));
+            last = now;
+        }, 100);
+        this.delayTimer.unref();
+    }
+    finish() {
+        if (this.finished)
+            return;
+        this.finished = true;
+        if (this.delayTimer) {
+            clearInterval(this.delayTimer);
+            this.delayTimer = undefined;
+            activeDelaySamplers--;
+        }
+        const used = process.cpuUsage(this.cpu);
+        this.observe('sdk.process_cpu', (used.user + used.system) / 1000);
+        this.mark('prepared_ms');
+    }
+    snapshot(v2 = true) {
+        const measurements = [...this.measurements].filter(([name]) => v2 || NAMES.slice(0, 6).includes(name))
+            .map(([name, value]) => ({ name, count: value.count, work_ms: value.work_ms, max_ms: value.max_ms, ...(v2 ? { histogram: [...value.histogram] } : {}) }));
+        return { schema_version: v2 ? 'sdk-performance/v2' : 'sdk-performance/v1', measurements, counters: { ...this.counters, ...(v2 && this.sourceHistory?.complete ? { source_renewals: this.sourceRenewals } : {}) },
+            ...(v2 ? { gauges: { ...this.gauges }, milestones: { ...this.milestones }, unmeasured: NAMES.slice(6).filter(name => !this.measurements.has(name)), detail_dropped: this.dropped } : {}) };
+    }
+}

package/dist/provider-signing.d.ts

@@ -63,7 +63,15 @@ export declare function inspectDestinationObject(destination: ProviderDestinatio
     versionId: string | undefined;
     metadata: Record<string, string>;
 }>;
+export declare function boundedGrantExpiry(url: string, upperBound: string): string;
+export type SourceRouteGrant = {
+    url: string;
+    headers: Record<string, string>;
+    expiresAt: string;
+};
+export declare function signSourceChunk(input: Parameters<typeof signSourceRoute>[0]): Promise<SourceRouteGrant>;
 export declare function signDestinationRoute(input: {
+    sourceGrant?: Promise<SourceRouteGrant>;
     chunk: ChunkSigningPlanItem;
     target: ChunkDestinationSigningTarget;
     source?: ProviderSourceConfig;
@@ -109,6 +117,16 @@ export declare function signDestinationReadRange(input: {
     url: string;
     headers: Record<string, string>;
 }>;
+declare function signSourceRoute(input: {
+    source?: ProviderSourceConfig;
+    fallbackUrl: string;
+    chunk: ChunkSigningPlanItem;
+    expiresIn: number;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    url: string;
+    headers: Record<string, string>;
+}>;
 export declare function signDestinationUrl(input: {
     contentMd5?: string;
     destination: ProviderDestinationConfig;
@@ -118,8 +136,10 @@ export declare function signDestinationUrl(input: {
     expiresIn: number;
     fetchImpl?: typeof fetch;
 }): Promise<string>;
+export declare function releaseProviderClients(configs: Array<ProviderSourceConfig | ProviderDestinationConfig>): void;
 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;
 export declare function s3CompatibleForcePathStyle(source: AnyS3CompatibleProviderConfig, endpoint?: string | undefined): boolean | undefined;
 export declare function isHuggingFaceProvider(config: ProviderSourceConfig | ProviderDestinationConfig): config is HuggingFaceProviderConfig;
+export {};