@qvac/sdk 0.18.2 → 0.19.0

package/dist/server/rpc/handlers/load-model/download-manager.js

@@ -1,308 +0,0 @@
-import { AbortController } from 'bare-abort-controller';
-import { DownloadCancelledError, InferenceCancelledError } from '../../../../utils/errors-server.js';
-import { getServerLogger } from '../../../../logging/index.js';
-import { getRequestRegistry } from '../../../../server/bare/runtime/index.js';
-const logger = getServerLogger();
-const activeTransfers = new Map();
-let nextSubscriberId = 0;
-function createSubscriber(onProgress, requestId) {
-    let resolve;
-    let reject;
-    const promise = new Promise((res, rej) => {
-        resolve = res;
-        reject = rej;
-    });
-    return {
-        id: String(nextSubscriberId++),
-        onProgress,
-        settled: false,
-        resolve,
-        reject,
-        promise,
-        requestId
-    };
-}
-function settleSubscriber(subscriber, result) {
-    if (subscriber.settled)
-        return;
-    subscriber.settled = true;
-    if (result instanceof Error) {
-        subscriber.reject(result);
-    }
-    else {
-        subscriber.resolve(result);
-    }
-}
-function deliverProgress(transfer, subscriber, progress) {
-    if (subscriber.settled || !subscriber.onProgress)
-        return;
-    try {
-        subscriber.onProgress(progress);
-    }
-    catch (err) {
-        const error = err instanceof Error ? err : new Error(String(err));
-        logger.warn('Progress callback threw; detaching subscriber', {
-            downloadKey: transfer.downloadKey,
-            subscriberId: subscriber.id,
-            error
-        });
-        settleSubscriber(subscriber, error);
-        removeSubscriber(transfer, subscriber.id);
-    }
-}
-function broadcastTransferProgress(transfer, progress) {
-    transfer.lastProgress = progress;
-    for (const sub of Array.from(transfer.subscribers.values())) {
-        deliverProgress(transfer, sub, progress);
-    }
-}
-/**
- * Idempotent: remove the subscriber from the transfer's roster and tear
- * the transfer down iff no subscribers remain. Wired from two places per
- * subscriber:
- *
- *   - the `request.signal.addEventListener("abort", ...)` listener that
- *     fires when `registry.cancel({ requestId })` aborts the request's
- *     context — this is the "user clicked Stop" cancel path;
- *   - `request.scope.defer(...)` which runs at request scope unwind —
- *     the safety net catching every other unwind path (handler returns,
- *     handler throws for a non-cancel reason, awaited promise settled
- *     and the `await using` falls out of scope on the success path).
- *
- * Both ends call this helper so an already-cleaned-up subscriber is a
- * no-op the second time around.
- */
-function removeSubscriber(transfer, subscriberId) {
-    if (!transfer.subscribers.has(subscriberId))
-        return;
-    transfer.subscribers.delete(subscriberId);
-    maybeCancelTransfer(transfer);
-}
-/**
- * Last-subscriber rule: when every caller has detached (cancel or
- * progress-callback throw), abort the shared transfer so the underlying
- * HTTP / hyperdrive download tears down. Until then the transfer keeps
- * running for the remaining subscribers — the content-addressed dedup
- * semantics callers rely on.
- */
-function maybeCancelTransfer(transfer) {
-    if (transfer.subscribers.size > 0)
-        return;
-    if (transfer.abortController.signal.aborted)
-        return;
-    logger.debug(`[download-manager] last subscriber left, aborting transfer ${transfer.downloadKey}`);
-    transfer.abortController.abort();
-}
-function attachRequestBinding(transfer, subscriber, request) {
-    const onAbort = () => {
-        if (!subscriber.settled) {
-            settleSubscriber(subscriber, new InferenceCancelledError(request.requestId));
-        }
-        removeSubscriber(transfer, subscriber.id);
-    };
-    if (request.signal.aborted) {
-        onAbort();
-        return;
-    }
-    request.signal.addEventListener('abort', onAbort, { once: true });
-    // Safety net: scope unwind on any handler exit path triggers the same
-    // cleanup. If the abort listener already ran it's a no-op. Cleaning
-    // up the abort listener here keeps the parent signal from carrying a
-    // dangling reference into the next request.
-    request.scope.defer(() => {
-        request.signal.removeEventListener('abort', onAbort);
-        if (!subscriber.settled) {
-            settleSubscriber(subscriber, new InferenceCancelledError(request.requestId));
-        }
-        removeSubscriber(transfer, subscriber.id);
-    });
-}
-export function startOrJoinDownload(downloadKey, startDownload, onProgress, request) {
-    const existing = activeTransfers.get(downloadKey);
-    if (existing && !existing.abortController.signal.aborted) {
-        logger.info(`📥 Reusing existing download for: ${downloadKey}`);
-        const subscriber = createSubscriber(onProgress, request?.requestId);
-        existing.subscribers.set(subscriber.id, subscriber);
-        if (request) {
-            attachRequestBinding(existing, subscriber, request);
-        }
-        if (existing.lastProgress) {
-            deliverProgress(existing, subscriber, existing.lastProgress);
-        }
-        return {
-            promise: subscriber.promise,
-            joined: true,
-            getCacheHit: () => existing.cacheHit
-        };
-    }
-    const abortController = new AbortController();
-    const transfer = {
-        downloadKey,
-        abortController,
-        subscribers: new Map(),
-        clearCache: false
-    };
-    const initialSubscriber = createSubscriber(onProgress, request?.requestId);
-    transfer.subscribers.set(initialSubscriber.id, initialSubscriber);
-    activeTransfers.set(downloadKey, transfer);
-    if (request) {
-        attachRequestBinding(transfer, initialSubscriber, request);
-    }
-    const downloadPromise = startDownload({
-        broadcastProgress: (progress) => {
-            broadcastTransferProgress(transfer, progress);
-        },
-        signal: abortController.signal,
-        shouldClearCache: () => transfer.clearCache,
-        setCacheHit: (cacheHit) => {
-            transfer.cacheHit = cacheHit;
-        }
-    });
-    transfer.downloadPromise = downloadPromise;
-    downloadPromise
-        .then((path) => {
-        for (const sub of transfer.subscribers.values()) {
-            settleSubscriber(sub, path);
-        }
-    }, (error) => {
-        const rejection = error instanceof Error ? error : new Error(String(error));
-        for (const sub of transfer.subscribers.values()) {
-            settleSubscriber(sub, rejection);
-        }
-    })
-        .finally(() => {
-        if (activeTransfers.get(downloadKey) === transfer) {
-            activeTransfers.delete(downloadKey);
-        }
-    });
-    return {
-        promise: initialSubscriber.promise,
-        joined: false,
-        getCacheHit: () => transfer.cacheHit
-    };
-}
-/**
- * Legacy cancel entry point. Callers (`cancelHandler`'s deprecated
- * `case "downloadAsset"` arm, the shutdown sweep, intra-resolve
- * cleanup) call this with a `downloadKey`. The single source of cancel
- * routing is the request registry, so this function resolves each
- * subscriber's request via `registry.cancel({ requestId })`.
- *
- * Subscribers without a `requestId` (legacy callers that didn't pass a
- * registry binding) are settled directly with `DownloadCancelledError`
- * so we don't leak the transfer if a legacy code path holds the only
- * reference.
- */
-/**
- * Set `clearCache=true` on the transfer that owns the subscriber bound
- * to `requestId`, so when the registry's targeted cancel removes that
- * subscriber and we reach last-subscriber teardown, the partial
- * download file is deleted instead of preserved for automatic resume.
- *
- * Lookup is O(transfers * subscribers); transfers are short-lived and
- * subscriber counts per transfer are tiny in practice, so this is
- * fine. Returns `true` if a matching subscriber was found, `false`
- * otherwise — the cancel handler treats both cases identically (the
- * registry cancel still fires) and the return value is informational.
- *
- * Added in 0.11.0 to support `cancel({ requestId, clearCache: true })`
- * for download requests after the wire schema collapse removed the
- * `{ operation: "downloadAsset", downloadKey, clearCache }` arm. The
- * subscriber is the unit of `clearCache` even though the flag lives on
- * the shared transfer: if any subscriber on the transfer asks for
- * clearCache, the partial file is deleted when the last subscriber
- * leaves, matching the pre-collapse behaviour.
- */
-export function markClearCacheForRequest(requestId) {
-    for (const transfer of activeTransfers.values()) {
-        for (const sub of transfer.subscribers.values()) {
-            if (sub.requestId === requestId) {
-                transfer.clearCache = true;
-                return true;
-            }
-        }
-    }
-    return false;
-}
-export function cancelTransfer(downloadKey, clearCache = false) {
-    const transfer = activeTransfers.get(downloadKey);
-    if (!transfer)
-        return;
-    transfer.clearCache = clearCache;
-    const registry = getRequestRegistry();
-    const orphanSubs = [];
-    for (const sub of Array.from(transfer.subscribers.values())) {
-        if (sub.requestId !== undefined) {
-            registry.cancel({
-                requestId: sub.requestId,
-                reason: 'download-transfer-cancel'
-            });
-        }
-        else {
-            orphanSubs.push(sub);
-        }
-    }
-    if (orphanSubs.length === 0) {
-        return;
-    }
-    // Legacy subscribers (no registry binding): settle each with
-    // `DownloadCancelledError` and route removal through the
-    // `removeSubscriber` helper so the last-subscriber teardown rule is
-    // enforced in one place. Registry-bound subscribers are handled by
-    // their `attachRequestBinding` listener triggered above.
-    for (const sub of orphanSubs) {
-        settleSubscriber(sub, new DownloadCancelledError());
-        removeSubscriber(transfer, sub.id);
-    }
-}
-export function createHyperdriveDownloadKey(hyperdriveKey, modelFileName) {
-    return `${hyperdriveKey}:${modelFileName}`;
-}
-export function createHttpDownloadKey(url) {
-    return `http:${url}`;
-}
-export function createRegistryDownloadKey(registrySource, registryPath) {
-    return `registry:${registrySource}:${registryPath}`;
-}
-export function applyJoinedDownloadStats(result, hooks) {
-    if (!result.joined)
-        return result.promise;
-    return result.promise.then((path) => {
-        const cacheHit = result.getCacheHit();
-        if (cacheHit === true) {
-            hooks?.markCacheHit?.();
-        }
-        else if (cacheHit === false) {
-            hooks?.markCacheMiss?.();
-            hooks?.markSharedTransfer?.();
-        }
-        else {
-            hooks?.markSharedTransfer?.();
-        }
-        return path;
-    });
-}
-export function cancelAllDownloads() {
-    logger.info(`🧹 Cancelling ${activeTransfers.size} active downloads`);
-    for (const key of Array.from(activeTransfers.keys())) {
-        cancelTransfer(key);
-    }
-}
-let isCleaningUp = false;
-export async function cleanupDownloads() {
-    if (isCleaningUp)
-        return;
-    isCleaningUp = true;
-    try {
-        const downloadPromises = Array.from(activeTransfers.values())
-            .filter((t) => t.downloadPromise !== undefined)
-            .map((t) => t.downloadPromise.catch(() => { }));
-        cancelAllDownloads();
-        if (downloadPromises.length > 0) {
-            await Promise.allSettled(downloadPromises);
-        }
-    }
-    catch (error) {
-        logger.error('❌ Error during download cleanup:', error);
-    }
-}

package/dist/server/rpc/handlers/load-model/download-stats.d.ts

@@ -1,8 +0,0 @@
-import type { ModelProgressUpdate } from '../../../../schemas/index.js';
-import type { DownloadStats, DownloadResult, DownloadHooks, ResolveResult } from './types.js';
-import type { ExplicitRegistryMetadata } from './registry-metadata.js';
-export declare function downloadModelFromHttpWithStats(url: string, progressCallback?: (progress: ModelProgressUpdate) => void, downloadHooks?: DownloadHooks): Promise<DownloadResult>;
-export declare function downloadModelFromRegistryWithStats(registryPath: string, registrySource: string, progressCallback?: (progress: ModelProgressUpdate) => void, expectedChecksum?: string, downloadHooks?: DownloadHooks, explicitMetadata?: ExplicitRegistryMetadata): Promise<DownloadResult>;
-export declare function downloadModelFromHyperdriveWithStats(hyperdriveKey: string, modelFileName: string, seed?: boolean, progressCallback?: (progress: ModelProgressUpdate) => void, downloadHooks?: DownloadHooks): Promise<DownloadResult>;
-export declare function mergeDownloadStats(results: ResolveResult[]): DownloadStats | undefined;
-//# sourceMappingURL=download-stats.d.ts.map

package/dist/server/rpc/handlers/load-model/download-stats.js

@@ -1,126 +0,0 @@
-import { downloadModelFromHttp } from './http.js';
-import { downloadModelFromRegistry } from './registry.js';
-import { downloadModelFromHyperdrive } from './hyperdrive.js';
-import { nowMs } from '../../../../profiling/index.js';
-function createStatsCollector() {
-    return {
-        maxBytesDownloaded: 0,
-        startTimeMs: nowMs(),
-        cacheHit: undefined,
-        sharedTransfer: false,
-        checksumValidationTimeMsTotal: 0
-    };
-}
-function createStatsHooks(collector) {
-    return {
-        markCacheHit: () => {
-            if (collector.cacheHit === undefined) {
-                collector.cacheHit = true;
-                collector.maxBytesDownloaded = 0;
-            }
-        },
-        markCacheMiss: () => {
-            collector.cacheHit = false;
-        },
-        markSharedTransfer: () => {
-            collector.sharedTransfer = true;
-        },
-        addChecksumValidationTimeMs: (durationMs) => {
-            collector.checksumValidationTimeMsTotal += durationMs;
-        }
-    };
-}
-function wrapProgressCallback(collector, originalCallback) {
-    return (progress) => {
-        // Don't track bytes for cache hits (they're not real network transfer)
-        if (collector.cacheHit !== true) {
-            const downloaded = progress.fileSetInfo?.overallDownloaded ??
-                progress.shardInfo?.overallDownloaded ??
-                progress.downloaded ??
-                0;
-            collector.maxBytesDownloaded = Math.max(collector.maxBytesDownloaded, downloaded);
-        }
-        originalCallback?.(progress);
-    };
-}
-function computeStats(collector) {
-    const downloadTimeMs = nowMs() - collector.startTimeMs;
-    const totalBytesDownloaded = collector.maxBytesDownloaded;
-    const stats = {};
-    if (collector.sharedTransfer) {
-        stats.sharedTransfer = true;
-    }
-    if (collector.cacheHit !== undefined) {
-        stats.cacheHit = collector.cacheHit;
-    }
-    if (collector.checksumValidationTimeMsTotal > 0) {
-        stats.checksumValidationTimeMs = collector.checksumValidationTimeMsTotal;
-    }
-    if (collector.cacheHit === true) {
-        return Object.keys(stats).length > 0 ? stats : undefined;
-    }
-    if (collector.sharedTransfer) {
-        if (downloadTimeMs > 0) {
-            stats.downloadTimeMs = downloadTimeMs;
-        }
-        return Object.keys(stats).length > 0 ? stats : undefined;
-    }
-    if (totalBytesDownloaded > 0) {
-        stats.downloadTimeMs = downloadTimeMs;
-        stats.totalBytesDownloaded = totalBytesDownloaded;
-        if (downloadTimeMs > 0) {
-            stats.downloadSpeedBps = (totalBytesDownloaded * 1000) / downloadTimeMs;
-        }
-    }
-    return Object.keys(stats).length > 0 ? stats : undefined;
-}
-export async function downloadModelFromHttpWithStats(url, progressCallback, downloadHooks) {
-    const collector = createStatsCollector();
-    const hooks = { ...downloadHooks, ...createStatsHooks(collector) };
-    const wrappedCallback = wrapProgressCallback(collector, progressCallback);
-    const path = await downloadModelFromHttp(url, wrappedCallback, hooks);
-    const stats = computeStats(collector);
-    return stats ? { path, stats } : { path };
-}
-export async function downloadModelFromRegistryWithStats(registryPath, registrySource, progressCallback, expectedChecksum, downloadHooks, explicitMetadata) {
-    const collector = createStatsCollector();
-    const hooks = { ...downloadHooks, ...createStatsHooks(collector) };
-    const wrappedCallback = wrapProgressCallback(collector, progressCallback);
-    const path = await downloadModelFromRegistry(registryPath, registrySource, wrappedCallback, expectedChecksum, hooks, explicitMetadata);
-    const stats = computeStats(collector);
-    return stats ? { path, stats } : { path };
-}
-export async function downloadModelFromHyperdriveWithStats(hyperdriveKey, modelFileName, seed, progressCallback, downloadHooks) {
-    const collector = createStatsCollector();
-    const hooks = { ...downloadHooks, ...createStatsHooks(collector) };
-    const wrappedCallback = wrapProgressCallback(collector, progressCallback);
-    const path = await downloadModelFromHyperdrive(hyperdriveKey, modelFileName, seed, wrappedCallback, hooks);
-    const stats = computeStats(collector);
-    return stats ? { path, stats } : { path };
-}
-export function mergeDownloadStats(results) {
-    const stats = results
-        .map((r) => r.downloadStats)
-        .filter((s) => s !== undefined);
-    if (stats.length === 0)
-        return undefined;
-    const downloadTimeMs = Math.max(...stats.map((s) => s.downloadTimeMs ?? 0));
-    const totalBytesDownloaded = stats.reduce((sum, s) => sum + (s.totalBytesDownloaded ?? 0), 0);
-    const checksumValidationTimeMs = stats.reduce((sum, s) => sum + (s.checksumValidationTimeMs ?? 0), 0);
-    const cacheHitValues = stats.map((s) => s.cacheHit).filter((v) => v !== undefined);
-    const merged = {};
-    if (downloadTimeMs > 0)
-        merged.downloadTimeMs = downloadTimeMs;
-    if (totalBytesDownloaded > 0)
-        merged.totalBytesDownloaded = totalBytesDownloaded;
-    if (downloadTimeMs > 0 && totalBytesDownloaded > 0) {
-        merged.downloadSpeedBps = (totalBytesDownloaded * 1000) / downloadTimeMs;
-    }
-    if (checksumValidationTimeMs > 0)
-        merged.checksumValidationTimeMs = checksumValidationTimeMs;
-    if (cacheHitValues.length > 0)
-        merged.cacheHit = cacheHitValues.every(Boolean);
-    if (stats.some((s) => s.sharedTransfer))
-        merged.sharedTransfer = true;
-    return Object.keys(merged).length > 0 ? merged : undefined;
-}

package/dist/server/rpc/handlers/load-model/handler.d.ts

@@ -1,3 +0,0 @@
-import type { LoadModelRequest, LoadModelResponse, ModelProgressUpdate } from '../../../../schemas/index.js';
-export declare function handleLoadModel(request: LoadModelRequest, progressCallback?: (update: ModelProgressUpdate) => void): Promise<LoadModelResponse>;
-//# sourceMappingURL=handler.d.ts.map