@syncular/server 0.0.6-96 → 0.1.0

package/dist/blobs/manager.d.ts

@@ -4,7 +4,7 @@
  * Orchestrates blob uploads and downloads using a pluggable storage adapter.
  * Handles metadata tracking, upload verification, and garbage collection.
  */
-import type { BlobStorageAdapter } from '@syncular/core';
+import type { BlobMetadata, BlobStorageAdapter, BlobUploadCompleteResponse, BlobUploadInitResponse } from '@syncular/core';
 import { type Kysely } from 'kysely';
 import type { SyncBlobUploadsDb } from './types';
 export interface BlobManagerOptions<DB extends SyncBlobUploadsDb = SyncBlobUploadsDb> {
@@ -16,17 +16,60 @@ export interface BlobManagerOptions<DB extends SyncBlobUploadsDb = SyncBlobUploa
     defaultExpiresIn?: number;
     /** How long incomplete uploads are kept before cleanup. Default: 86400 (24 hours) */
     uploadTtlSeconds?: number;
+    /** Optional cleanup throughput tuning knobs. */
+    cleanupTuning?: BlobCleanupTuning;
 }
+export interface BlobCleanupTuning {
+    /** Cleanup select/delete batch size. Default: 250 */
+    batchSize?: number;
+    /** Max concurrent storage deletes during cleanup. Default: 8 */
+    storageDeleteConcurrency?: number;
+    /** Max concurrent reference checks for completed uploads. Default: 16 */
+    referenceCheckConcurrency?: number;
+}
+export declare const BLOB_CLEANUP_TUNING_PRESETS: {
+    readonly server: {
+        readonly batchSize: 500;
+        readonly storageDeleteConcurrency: 16;
+        readonly referenceCheckConcurrency: 24;
+    };
+    readonly edge: {
+        readonly batchSize: 100;
+        readonly storageDeleteConcurrency: 4;
+        readonly referenceCheckConcurrency: 8;
+    };
+};
 export interface InitiateUploadOptions {
     hash: string;
     size: number;
     mimeType: string;
     actorId: string;
+    partitionId?: string;
 }
 export interface GetDownloadUrlOptions {
     hash: string;
     /** Optional: verify actor has access to this blob via a scope check */
     actorId?: string;
+    partitionId?: string;
+}
+export interface CompleteUploadOptions {
+    /**
+     * Optional actor identity to authorize upload completion.
+     * When provided, only the initiating actor may mark an upload complete.
+     */
+    actorId?: string;
+    partitionId?: string;
+}
+export interface BlobUploadRecord {
+    partitionId: string;
+    hash: string;
+    size: number;
+    mimeType: string;
+    status: 'pending' | 'complete';
+    actorId: string;
+    createdAt: string;
+    expiresAt: string;
+    completedAt: string | null;
 }
 /**
  * Create a blob manager for handling server-side blob operations.
@@ -37,61 +80,39 @@ export declare function createBlobManager<DB extends SyncBlobUploadsDb>(options:
      *
      * Checks for deduplication and returns a presigned URL for uploading.
      */
-    initiateUpload(opts: InitiateUploadOptions): Promise<{
-        exists: boolean;
-        uploadId?: string | undefined;
-        uploadUrl?: string | undefined;
-        uploadMethod?: "POST" | "PUT" | undefined;
-        uploadHeaders?: Record<string, string> | undefined;
-        chunkSize?: number | undefined;
-    }>;
+    initiateUpload(opts: InitiateUploadOptions): Promise<BlobUploadInitResponse>;
     /**
      * Complete a blob upload.
      *
      * Verifies the blob exists in storage and marks the upload as complete.
      */
-    completeUpload(hash: string): Promise<{
-        ok: boolean;
-        metadata?: {
-            hash: string;
-            size: number;
-            mimeType: string;
-            createdAt: string;
-            expiresAt?: string | undefined;
-            uploadComplete: boolean;
-        } | undefined;
-        error?: string | undefined;
-    }>;
+    completeUpload(hash: string, options?: CompleteUploadOptions): Promise<BlobUploadCompleteResponse>;
     /**
      * Get a presigned download URL for a blob.
      */
     getDownloadUrl(opts: GetDownloadUrlOptions): Promise<{
         url: string;
         expiresAt: string;
-        metadata: {
-            hash: string;
-            size: number;
-            mimeType: string;
-            createdAt: string;
-            expiresAt?: string | undefined;
-            uploadComplete: boolean;
-        };
+        metadata: BlobMetadata;
     }>;
+    /**
+     * Get upload record for a blob hash, including pending uploads.
+     */
+    getUploadRecord(hash: string, options?: {
+        partitionId?: string;
+    }): Promise<BlobUploadRecord | null>;
     /**
      * Get blob metadata without generating a download URL.
      */
-    getMetadata(hash: string): Promise<{
-        hash: string;
-        size: number;
-        mimeType: string;
-        createdAt: string;
-        expiresAt?: string | undefined;
-        uploadComplete: boolean;
-    } | null>;
+    getMetadata(hash: string, options?: {
+        partitionId?: string;
+    }): Promise<BlobMetadata | null>;
     /**
      * Check if a blob exists and is complete.
      */
-    exists(hash: string): Promise<boolean>;
+    exists(hash: string, options?: {
+        partitionId?: string;
+    }): Promise<boolean>;
     /**
      * Clean up expired/orphaned uploads.
      *
@@ -101,10 +122,12 @@ export declare function createBlobManager<DB extends SyncBlobUploadsDb>(options:
      */
     cleanup(options?: {
         /** Check if a blob hash is referenced by any row */
-        isReferenced?: ((hash: string) => Promise<boolean>) | undefined;
+        isReferenced?: (hash: string) => Promise<boolean>;
         /** Delete from storage too (not just tracking table) */
-        deleteFromStorage?: boolean | undefined;
-    } | undefined): Promise<{
+        deleteFromStorage?: boolean;
+        /** Optional partition filter for cleanup */
+        partitionId?: string;
+    }): Promise<{
         deleted: number;
     }>;
     /** The underlying storage adapter */
@@ -120,6 +143,8 @@ export interface BlobCleanupSchedulerOptions {
     deleteFromStorage?: boolean;
     /** Optional: Check if a blob hash is referenced by any row */
     isReferenced?: (hash: string) => Promise<boolean>;
+    /** Optional partition to scope cleanup. Defaults to "default". */
+    partitionId?: string;
     /** Optional: Called after each cleanup run */
     onCleanup?: (result: {
         deleted: number;
@@ -164,8 +189,8 @@ export declare function createBlobCleanupScheduler(options: BlobCleanupScheduler
      * Optionally runs an immediate cleanup before starting the interval.
      */
     start(options?: {
-        immediate?: boolean | undefined;
-    } | undefined): void;
+        immediate?: boolean;
+    }): void;
     /**
      * Stop the cleanup scheduler.
      */
@@ -175,7 +200,7 @@ export declare function createBlobCleanupScheduler(options: BlobCleanupScheduler
      */
     runOnce(): Promise<{
         deleted: number;
-        error?: Error | undefined;
+        error?: Error;
     }>;
     /**
      * Check if the scheduler is currently active.

package/dist/blobs/manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/blobs/manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAEV,kBAAkB,EAGnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,KAAK,MAAM,EAAO,MAAM,QAAQ,CAAC;AAC1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAMjD,MAAM,WAAW,kBAAkB,CACjC,EAAE,SAAS,iBAAiB,GAAG,iBAAiB;IAEhD,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IACf,+CAA+C;IAC/C,OAAO,EAAE,kBAAkB,CAAC;IAC5B,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,SAAS,iBAAiB,EAC5D,OAAO,EAAE,kBAAkB,CAAC,EAAE,CAAC;IAU7B;;;;OAIG;;;;;;;;;IA6GH;;;;OAIG;;;;;;;;;;;;;IA6EH;;OAEG;;;;;;;;;;;;;IAqDH;;OAEG;;;;;;;;;IAkCH;;OAEG;;IAcH;;;;;;OAMG;;QAED,oDAAoD;;QAEpD,wDAAwD;;;;;IAiE1D,qCAAqC;;EAGxC;AAED,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAM/D,MAAM,WAAW,2BAA2B;IAC1C,4BAA4B;IAC5B,WAAW,EAAE,WAAW,CAAC;IACzB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,8DAA8D;IAC9D,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,8CAA8C;IAC9C,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE,KAAK,IAAI,CAAC;CAClE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B;IAsClC;;;OAGG;;;;IAeH;;OAEG;;IAQH;;OAEG;;;;;IAKH;;OAEG;;IAKH;;OAEG;;EAKN;AAMD,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF"}
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/blobs/manager.ts"],"names":[],"mappings":"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"}