@powersync/service-module-mongodb-storage 0.18.2 → 0.19.0

package/dist/storage/implementation/v3/object-storage/ObjectStorageLifecycle.d.ts

@@ -0,0 +1,70 @@
+import { mongo } from '@powersync/lib-service-mongodb';
+import { Logger } from '@powersync/lib-services-framework';
+import * as bson from 'bson';
+import { VersionedPowerSyncMongoV3 } from '../VersionedPowerSyncMongoV3.js';
+import { BucketDataObjectStorage } from './BucketDataObjectStorage.js';
+import { ObjectStorage } from './ObjectStorage.js';
+export declare const OBJECT_STORAGE_UPLOAD_LEASE_MS: number;
+export declare const OBJECT_STORAGE_PUBLICATION_SAFETY_MARGIN_MS: number;
+export declare const OBJECT_STORAGE_REFERENCE_GRACE_MS: number;
+export interface PreparedObjectStorageUpload {
+    markerId: bson.ObjectId;
+    path: string;
+    deleteAfter: Date;
+}
+/**
+ * Coordinates the MongoDB outbox used to make object-storage changes recoverable.
+ *
+ * A MongoDB collection is used to track files that will be uploaded, or should be deleted.
+ * By using a MongoDB collection, we can use the same transaction that creates or removes
+ * references to these files, making the operations atomic.
+ *
+ * These markers indicate which files should be deleted - either by being orphaned during create,
+ * or after references to them are removed.
+ */
+export declare class ObjectStorageLifecycle {
+    private readonly db;
+    private readonly replicationStreamId;
+    private readonly objectStorage;
+    readonly bucketData: BucketDataObjectStorage;
+    constructor(db: VersionedPowerSyncMongoV3, replicationStreamId: number, objectStorage: ObjectStorage);
+    streamPrefix(): string;
+    definitionPrefix(definitionId: string): string;
+    allocatePath(definitionId: string, bucket: string, minOp: bigint, maxOp: bigint): string;
+    /**
+     * Indicate that files will be uploaded to S3.
+     *
+     * These markers are expected to be removed using publishUploads(). If that does not happen within
+     * the grace period, the files will be deleted.
+     */
+    prepareUploads(paths: string[], now?: Date): Promise<PreparedObjectStorageUpload[]>;
+    canPublish(upload: PreparedObjectStorageUpload, now?: Date): boolean;
+    /**
+     * Remove markers for files that have finished uploading, and are now referenced from other documents.
+     *
+     * Call this in the same transaction as the one creating the references.
+     */
+    publishUploads(uploads: PreparedObjectStorageUpload[], session: mongo.ClientSession): Promise<void>;
+    /**
+     * Mark old paths for deletion.
+     *
+     * By marking for deletion instead of immediately deleting:
+     * 1. This avoids inconsistencies/orphaned files between MongoDB and S3, by allowing the markers to
+     *    be persisted transactionally, while the deletes happen asynchronously and can be retried.
+     * 2. The deletes are delayed, giving clients a grace period to continue using the files for
+     *    in-progress requests.
+     *
+     * Call this in the same transaction as the one removing the references to these files.
+     */
+    retire(paths: Iterable<string>, session: mongo.ClientSession, now?: Date): Promise<void>;
+    /**
+     * Discover and delete objects by their storage prefix
+     * without touching the database.
+     */
+    deletePrefix(prefix: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        objectCount: number;
+    }>;
+    cleanup(logger: Logger): Promise<void>;
+}

package/dist/storage/implementation/v3/object-storage/ObjectStorageLifecycle.js

@@ -0,0 +1,146 @@
+import * as bson from 'bson';
+import { createHash, randomUUID } from 'node:crypto';
+import { BucketDataObjectStorage } from './BucketDataObjectStorage.js';
+export const OBJECT_STORAGE_UPLOAD_LEASE_MS = 60 * 60 * 1000;
+export const OBJECT_STORAGE_PUBLICATION_SAFETY_MARGIN_MS = 2 * 60 * 1000;
+export const OBJECT_STORAGE_REFERENCE_GRACE_MS = 15 * 60 * 1000;
+/**
+ * Protect against arbitrary-long bucket names and parameters exceeding the S3 key length limits.
+ *
+ * Any bucket name over this length is hashed.
+ */
+const MAX_READABLE_BUCKET_SEGMENT_BYTES = 128;
+/**
+ * Coordinates the MongoDB outbox used to make object-storage changes recoverable.
+ *
+ * A MongoDB collection is used to track files that will be uploaded, or should be deleted.
+ * By using a MongoDB collection, we can use the same transaction that creates or removes
+ * references to these files, making the operations atomic.
+ *
+ * These markers indicate which files should be deleted - either by being orphaned during create,
+ * or after references to them are removed.
+ */
+export class ObjectStorageLifecycle {
+    db;
+    replicationStreamId;
+    objectStorage;
+    bucketData;
+    constructor(db, replicationStreamId, objectStorage) {
+        this.db = db;
+        this.replicationStreamId = replicationStreamId;
+        this.objectStorage = objectStorage;
+        this.bucketData = new BucketDataObjectStorage(objectStorage);
+    }
+    streamPrefix() {
+        return `bucket-data/${this.replicationStreamId}/`;
+    }
+    definitionPrefix(definitionId) {
+        return `${this.streamPrefix()}${definitionId}/`;
+    }
+    allocatePath(definitionId, bucket, minOp, maxOp) {
+        // Preserve readable paths for normal buckets, but bound user-controlled
+        // parameter values so they cannot consume the S3 key-length budget.
+        const escapedBucket = encodeURIComponent(bucket);
+        const bucketSegment = Buffer.byteLength(escapedBucket, 'utf8') <= MAX_READABLE_BUCKET_SEGMENT_BYTES
+            ? escapedBucket
+            : `sha256-${createHash('sha256').update(bucket).digest('base64url')}`;
+        return `${this.definitionPrefix(definitionId)}${bucketSegment}/${minOp}-${maxOp}-${randomUUID()}.bson`;
+    }
+    /**
+     * Indicate that files will be uploaded to S3.
+     *
+     * These markers are expected to be removed using publishUploads(). If that does not happen within
+     * the grace period, the files will be deleted.
+     */
+    async prepareUploads(paths, now = new Date()) {
+        const deleteAfter = new Date(now.getTime() + OBJECT_STORAGE_UPLOAD_LEASE_MS);
+        const uploads = paths.map((path) => ({ markerId: new bson.ObjectId(), path, deleteAfter }));
+        if (uploads.length) {
+            await this.db.pendingObjectStorageDeletes(this.replicationStreamId).insertMany(uploads.map((upload) => ({
+                _id: upload.markerId,
+                path: upload.path,
+                delete_after: upload.deleteAfter
+            })));
+        }
+        return uploads;
+    }
+    canPublish(upload, now = new Date()) {
+        return now.getTime() < upload.deleteAfter.getTime() - OBJECT_STORAGE_PUBLICATION_SAFETY_MARGIN_MS;
+    }
+    /**
+     * Remove markers for files that have finished uploading, and are now referenced from other documents.
+     *
+     * Call this in the same transaction as the one creating the references.
+     */
+    async publishUploads(uploads, session) {
+        for (const upload of uploads) {
+            if (!this.canPublish(upload)) {
+                throw new Error(`Object storage publication lease expired for ${upload.path}`);
+            }
+        }
+        if (uploads.length === 0) {
+            return;
+        }
+        const result = await this.db
+            .pendingObjectStorageDeletes(this.replicationStreamId)
+            .deleteMany({ _id: { $in: uploads.map((upload) => upload.markerId) } }, { session });
+        if (result.deletedCount !== uploads.length) {
+            throw new Error(`Missing object storage publication markers`);
+        }
+    }
+    /**
+     * Mark old paths for deletion.
+     *
+     * By marking for deletion instead of immediately deleting:
+     * 1. This avoids inconsistencies/orphaned files between MongoDB and S3, by allowing the markers to
+     *    be persisted transactionally, while the deletes happen asynchronously and can be retried.
+     * 2. The deletes are delayed, giving clients a grace period to continue using the files for
+     *    in-progress requests.
+     *
+     * Call this in the same transaction as the one removing the references to these files.
+     */
+    async retire(paths, session, now = new Date()) {
+        const markers = Array.from(paths, (path) => ({
+            _id: new bson.ObjectId(),
+            path,
+            delete_after: new Date(now.getTime() + OBJECT_STORAGE_REFERENCE_GRACE_MS)
+        }));
+        if (markers.length) {
+            await this.db.pendingObjectStorageDeletes(this.replicationStreamId).insertMany(markers, { session });
+        }
+    }
+    /**
+     * Discover and delete objects by their storage prefix
+     * without touching the database.
+     */
+    async deletePrefix(prefix, options) {
+        return this.objectStorage.deletePrefix(prefix, { signal: options?.signal });
+    }
+    async cleanup(logger) {
+        const markers = this.db.pendingObjectStorageDeletes(this.replicationStreamId);
+        const cursor = markers.find({ delete_after: { $lte: new Date() } });
+        let batch = [];
+        const deleteBatch = async () => {
+            if (batch.length === 0) {
+                return;
+            }
+            const deleting = batch;
+            batch = [];
+            try {
+                await this.bucketData.delete(deleting.map((marker) => marker.path));
+                await markers.deleteMany({ _id: { $in: deleting.map((marker) => marker._id) } });
+            }
+            catch (error) {
+                logger.warn('Failed to clean up object storage deletion markers; will retry during the next compaction', error);
+            }
+        };
+        for await (const marker of cursor) {
+            batch.push(marker);
+            if (batch.length === 500) {
+                await deleteBatch();
+            }
+        }
+        await deleteBatch();
+    }
+}
+//# sourceMappingURL=ObjectStorageLifecycle.js.map

package/dist/storage/implementation/v3/object-storage/ObjectStorageLifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObjectStorageLifecycle.js","sourceRoot":"","sources":["../../../../../src/storage/implementation/v3/object-storage/ObjectStorageLifecycle.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAC7D,MAAM,CAAC,MAAM,2CAA2C,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AACzE,MAAM,CAAC,MAAM,iCAAiC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAChE;;;;GAIG;AACH,MAAM,iCAAiC,GAAG,GAAG,CAAC;AAQ9C;;;;;;;;;GASG;AACH,MAAM,OAAO,sBAAsB;IAId;IACA;IACA;IALV,UAAU,CAA0B;IAE7C,YACmB,EAA6B,EAC7B,mBAA2B,EAC3B,aAA4B;QAF5B,OAAE,GAAF,EAAE,CAA2B;QAC7B,wBAAmB,GAAnB,mBAAmB,CAAQ;QAC3B,kBAAa,GAAb,aAAa,CAAe;QAE7C,IAAI,CAAC,UAAU,GAAG,IAAI,uBAAuB,CAAC,aAAa,CAAC,CAAC;IAC/D,CAAC;IAED,YAAY;QACV,OAAO,eAAe,IAAI,CAAC,mBAAmB,GAAG,CAAC;IACpD,CAAC;IAED,gBAAgB,CAAC,YAAoB;QACnC,OAAO,GAAG,IAAI,CAAC,YAAY,EAAE,GAAG,YAAY,GAAG,CAAC;IAClD,CAAC;IAED,YAAY,CAAC,YAAoB,EAAE,MAAc,EAAE,KAAa,EAAE,KAAa;QAC7E,wEAAwE;QACxE,oEAAoE;QACpE,MAAM,aAAa,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;QACjD,MAAM,aAAa,GACjB,MAAM,CAAC,UAAU,CAAC,aAAa,EAAE,MAAM,CAAC,IAAI,iCAAiC;YAC3E,CAAC,CAAC,aAAa;YACf,CAAC,CAAC,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QAC1E,OAAO,GAAG,IAAI,CAAC,gBAAgB,CAAC,YAAY,CAAC,GAAG,aAAa,IAAI,KAAK,IAAI,KAAK,IAAI,UAAU,EAAE,OAAO,CAAC;IACzG,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,cAAc,CAAC,KAAe,EAAE,GAAG,GAAG,IAAI,IAAI,EAAE;QACpD,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,8BAA8B,CAAC,CAAC;QAC7E,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,IAAI,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;QAC5F,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,IAAI,CAAC,EAAE,CAAC,2BAA2B,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,UAAU,CAC5E,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;gBACvB,GAAG,EAAE,MAAM,CAAC,QAAQ;gBACpB,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,YAAY,EAAE,MAAM,CAAC,WAAW;aACjC,CAAC,CAAC,CACJ,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,UAAU,CAAC,MAAmC,EAAE,GAAG,GAAG,IAAI,IAAI,EAAE;QAC9D,OAAO,GAAG,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,GAAG,2CAA2C,CAAC;IACpG,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,cAAc,CAAC,OAAsC,EAAE,OAA4B;QACvF,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CAAC,gDAAgD,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;YACjF,CAAC;QACH,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE;aACzB,2BAA2B,CAAC,IAAI,CAAC,mBAAmB,CAAC;aACrD,UAAU,CAAC,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QACvF,IAAI,MAAM,CAAC,YAAY,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;QAChE,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,MAAM,CAAC,KAAuB,EAAE,OAA4B,EAAE,GAAG,GAAG,IAAI,IAAI,EAAE;QAClF,MAAM,OAAO,GAAkC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC1E,GAAG,EAAE,IAAI,IAAI,CAAC,QAAQ,EAAE;YACxB,IAAI;YACJ,YAAY,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,iCAAiC,CAAC;SAC1E,CAAC,CAAC,CAAC;QACJ,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,IAAI,CAAC,EAAE,CAAC,2BAA2B,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QACvG,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,YAAY,CAAC,MAAc,EAAE,OAAkC;QACnE,OAAO,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,MAAc;QAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,2BAA2B,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAC9E,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QACpE,IAAI,KAAK,GAAkC,EAAE,CAAC;QAE9C,MAAM,WAAW,GAAG,KAAK,IAAI,EAAE;YAC7B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACvB,OAAO;YACT,CAAC;YACD,MAAM,QAAQ,GAAG,KAAK,CAAC;YACvB,KAAK,GAAG,EAAE,CAAC;YACX,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;gBACpE,MAAM,OAAO,CAAC,UAAU,CAAC,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;YACnF,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,IAAI,CAAC,2FAA2F,EAAE,KAAK,CAAC,CAAC;YAClH,CAAC;QACH,CAAC,CAAC;QAEF,IAAI,KAAK,EAAE,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;YAClC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACnB,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBACzB,MAAM,WAAW,EAAE,CAAC;YACtB,CAAC;QACH,CAAC;QACD,MAAM,WAAW,EAAE,CAAC;IACtB,CAAC;CACF"}

package/dist/storage/implementation/v3/object-storage/S3ObjectStorage.d.ts

@@ -0,0 +1,42 @@
+import { S3Client } from '@aws-sdk/client-s3';
+import { type ObjectStorage, type ObjectStoragePutMetadata } from './ObjectStorage.js';
+export interface S3ObjectStorageOptions {
+    bucket: string;
+    region?: string;
+    prefix?: string;
+    endpoint?: string;
+    forcePathStyle?: boolean;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    concurrencyLimit?: number;
+}
+export declare class S3ObjectStorage implements ObjectStorage {
+    /**
+     * Public for tests only.
+     */
+    readonly client: S3Client;
+    private bucket;
+    private prefix;
+    private readonly operationSemaphore;
+    constructor(options: S3ObjectStorageOptions);
+    put(path: string, data: Uint8Array, metadata: ObjectStoragePutMetadata): Promise<void>;
+    get(path: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        data: Uint8Array;
+        metadata: ObjectStoragePutMetadata;
+    }>;
+    list(prefix: string, options?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<string>;
+    delete(paths: string[]): Promise<void>;
+    deletePrefix(prefix: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        objectCount: number;
+    }>;
+    private listPage;
+    private deleteFullPaths;
+    private fullPath;
+    private withOperation;
+}

package/dist/storage/implementation/v3/object-storage/S3ObjectStorage.js

@@ -0,0 +1,285 @@
+import { DeleteObjectsCommand, GetObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { acquireSemaphoreAbortable, isAbortError } from '@powersync/service-core';
+import { isThrottlingError, isTransientError } from '@smithy/core/retry';
+import { Semaphore } from 'async-mutex';
+import { ObjectStorageError } from './ObjectStorage.js';
+const DEFAULT_S3_OPERATION_CONCURRENCY = 16;
+const S3_DELETE_PREFIX_BATCH_SIZE = 1000;
+/**
+ * Slightly smaller than DEFAULT_S3_OPERATION_CONCURRENCY.
+ */
+const S3_DELETE_PREFIX_CONCURRENCY = 12;
+const MAX_S3_PREFIX_BYTES = 256;
+const SAFE_S3_KEY_BYTES = 896;
+export class S3ObjectStorage {
+    /**
+     * Public for tests only.
+     */
+    client;
+    bucket;
+    prefix;
+    operationSemaphore;
+    constructor(options) {
+        const concurrencyLimit = options.concurrencyLimit ?? DEFAULT_S3_OPERATION_CONCURRENCY;
+        if (!Number.isInteger(concurrencyLimit) || concurrencyLimit <= 0) {
+            throw new Error('S3 object storage concurrencyLimit must be a positive integer');
+        }
+        if ((options.accessKeyId == null) !== (options.secretAccessKey == null)) {
+            throw new Error('S3 object storage accessKeyId and secretAccessKey must be configured together');
+        }
+        const prefix = options.prefix ?? '';
+        if (Buffer.byteLength(prefix, 'utf8') > MAX_S3_PREFIX_BYTES) {
+            throw new Error(`S3 object storage prefix must be at most ${MAX_S3_PREFIX_BYTES} UTF-8 bytes`);
+        }
+        if (prefix.endsWith('/')) {
+            throw new Error('S3 object storage prefix must not end with "/"');
+        }
+        this.bucket = options.bucket;
+        this.prefix = prefix;
+        this.operationSemaphore = new Semaphore(concurrencyLimit);
+        this.client = new S3Client({
+            region: options.region,
+            endpoint: options.endpoint,
+            forcePathStyle: options.forcePathStyle,
+            credentials: options.accessKeyId && options.secretAccessKey
+                ? { accessKeyId: options.accessKeyId, secretAccessKey: options.secretAccessKey }
+                : undefined
+        });
+    }
+    async put(path, data, metadata) {
+        const fullPath = this.fullPath(path);
+        await using _ = await this.withOperation();
+        try {
+            await this.client.send(new PutObjectCommand({
+                Bucket: this.bucket,
+                Key: fullPath,
+                Body: data,
+                ContentType: metadata.contentType,
+                ContentEncoding: metadata.contentEncoding ?? undefined
+            }));
+        }
+        catch (error) {
+            throw s3OperationError('upload', fullPath, error);
+        }
+    }
+    async get(path, options) {
+        const fullPath = this.fullPath(path);
+        const signal = options?.signal;
+        await using _ = await this.withOperation(signal);
+        try {
+            const response = await this.client.send(new GetObjectCommand({
+                Bucket: this.bucket,
+                Key: fullPath
+            }), { abortSignal: signal });
+            const contentLength = response.ContentLength;
+            if (contentLength == null) {
+                throw new Error(`S3 download response for ${fullPath} is missing ContentLength`);
+            }
+            if (!Number.isSafeInteger(contentLength) || contentLength < 0) {
+                throw new Error(`S3 download response for ${fullPath} has invalid ContentLength ${contentLength}`);
+            }
+            const data = new Uint8Array(contentLength);
+            let offset = 0;
+            const stream = response.Body;
+            for await (const chunk of stream) {
+                signal?.throwIfAborted();
+                const nextOffset = offset + chunk.byteLength;
+                if (nextOffset > contentLength) {
+                    throw new Error(`S3 download ContentLength mismatch for ${fullPath}: expected ${contentLength} bytes, received at least ${nextOffset}`);
+                }
+                data.set(chunk, offset);
+                offset = nextOffset;
+            }
+            if (offset !== contentLength) {
+                throw new Error(`S3 download ContentLength mismatch for ${fullPath}: expected ${contentLength} bytes, received ${offset}`);
+            }
+            return {
+                data,
+                metadata: {
+                    contentType: response.ContentType ?? 'application/octet-stream',
+                    contentEncoding: response.ContentEncoding ?? null
+                }
+            };
+        }
+        catch (err) {
+            if (err.name === 'NoSuchKey' || err.Code === 'NoSuchKey') {
+                throw new ObjectStorageError(`S3 object not found: ${fullPath}`, { cause: err, retryable: false });
+            }
+            throw s3OperationError('download', fullPath, err);
+        }
+    }
+    async *list(prefix, options) {
+        const fullPrefix = this.fullPath(prefix);
+        let continuationToken;
+        const signal = options?.signal;
+        do {
+            signal?.throwIfAborted();
+            const response = await this.listPage(fullPrefix, continuationToken, signal);
+            for (const object of response.Contents ?? []) {
+                if (object.Key == null) {
+                    continue;
+                }
+                yield this.prefix ? object.Key.slice(this.prefix.length + 1) : object.Key;
+            }
+            continuationToken = response.IsTruncated ? response.NextContinuationToken : undefined;
+            if (response.IsTruncated && continuationToken == null) {
+                throw new Error(`S3 listing for ${fullPrefix} was truncated without a continuation token`);
+            }
+        } while (continuationToken != null);
+    }
+    async delete(paths) {
+        const fullPaths = paths.map((path) => ({ Key: this.fullPath(path) }));
+        await this.deleteFullPaths(fullPaths);
+    }
+    async deletePrefix(prefix, options) {
+        const fullPrefix = this.fullPath(prefix);
+        const signal = options?.signal;
+        let continuationToken;
+        let objectCount = 0;
+        const deleting = new Set();
+        let deleteError;
+        const scheduleDelete = (fullPaths) => {
+            let tracked;
+            tracked = this.deleteFullPaths(fullPaths, signal)
+                .catch((error) => {
+                deleteError ??= { error };
+            })
+                .finally(() => deleting.delete(tracked));
+            deleting.add(tracked);
+        };
+        const throwDeleteError = () => {
+            if (deleteError != null) {
+                throw deleteError.error;
+            }
+        };
+        let operationError;
+        try {
+            do {
+                signal?.throwIfAborted();
+                const response = await this.listPage(fullPrefix, continuationToken, signal);
+                throwDeleteError();
+                const fullPaths = [];
+                for (const object of response.Contents ?? []) {
+                    if (object.Key != null) {
+                        fullPaths.push({ Key: object.Key });
+                    }
+                }
+                objectCount += fullPaths.length;
+                if (fullPaths.length !== 0) {
+                    while (deleting.size >= S3_DELETE_PREFIX_CONCURRENCY) {
+                        await Promise.race(deleting);
+                        throwDeleteError();
+                    }
+                    scheduleDelete(fullPaths);
+                }
+                continuationToken = response.IsTruncated ? response.NextContinuationToken : undefined;
+                if (response.IsTruncated && continuationToken == null) {
+                    throw new Error(`S3 listing for ${fullPrefix} was truncated without a continuation token`);
+                }
+            } while (continuationToken != null);
+        }
+        catch (error) {
+            operationError = { error };
+        }
+        await Promise.all(deleting);
+        if (operationError != null) {
+            throw operationError.error;
+        }
+        throwDeleteError();
+        return { objectCount };
+    }
+    async listPage(fullPrefix, continuationToken, signal) {
+        try {
+            await using _ = await this.withOperation(signal);
+            return await this.client.send(new ListObjectsV2Command({
+                Bucket: this.bucket,
+                Prefix: fullPrefix,
+                ContinuationToken: continuationToken,
+                MaxKeys: S3_DELETE_PREFIX_BATCH_SIZE
+            }), { abortSignal: signal });
+        }
+        catch (error) {
+            throw s3OperationError('list', fullPrefix, error);
+        }
+    }
+    async deleteFullPaths(fullPaths, signal) {
+        if (fullPaths.length === 0)
+            return;
+        await using _ = await this.withOperation(signal);
+        let response;
+        try {
+            response = await this.client.send(new DeleteObjectsCommand({
+                Bucket: this.bucket,
+                Delete: { Objects: fullPaths, Quiet: true }
+            }), { abortSignal: signal });
+        }
+        catch (error) {
+            throw s3OperationError('delete', `${fullPaths.length} objects`, error);
+        }
+        if (response.Errors?.length) {
+            const errors = response.Errors.map((error) => `${error.Key}: ${error.Code}`).join(', ');
+            throw new ObjectStorageError(`Failed to delete S3 objects: ${errors}`, {
+                cause: response.Errors,
+                retryable: response.Errors.some((error) => isTransientS3Error({ name: error.Code }))
+            });
+        }
+    }
+    fullPath(path) {
+        const fullPath = this.prefix ? `${this.prefix}/${path}` : path;
+        const size = Buffer.byteLength(fullPath, 'utf8');
+        if (size > SAFE_S3_KEY_BYTES) {
+            throw new Error(`S3 object key is ${size} bytes, exceeding the safe limit of ${SAFE_S3_KEY_BYTES} bytes`);
+        }
+        return fullPath;
+    }
+    async withOperation(signal) {
+        signal?.throwIfAborted();
+        const acquired = signal
+            ? await acquireSemaphoreAbortable(this.operationSemaphore, signal)
+            : await this.operationSemaphore.acquire();
+        if (acquired === 'aborted') {
+            signal.throwIfAborted();
+            throw new Error('S3 operation aborted while waiting for a concurrency slot');
+        }
+        const [, release] = acquired;
+        if (signal?.aborted) {
+            release();
+            signal.throwIfAborted();
+        }
+        return {
+            [Symbol.asyncDispose]: async () => release()
+        };
+    }
+}
+function s3OperationError(operation, target, error) {
+    if (error instanceof ObjectStorageError) {
+        return error;
+    }
+    // Preserve abort errors so callers can distinguish cancellation from an S3
+    // failure and avoid retrying work after shutdown.
+    if (isAbortError(error)) {
+        return error;
+    }
+    const detail = error instanceof Error ? `: ${error.message}` : '';
+    return new ObjectStorageError(`S3 ${operation} failed for ${target}${detail}`, {
+        cause: error,
+        retryable: isTransientS3Error(error)
+    });
+}
+function isTransientS3Error(error) {
+    if (typeof error != 'object' || error == null) {
+        return false;
+    }
+    if (isAbortError(error)) {
+        return false;
+    }
+    const sdkError = error;
+    // Use the same classification as the AWS SDK retry middleware. The SDK
+    // returns the final error after its own attempt/quota limits are exhausted;
+    // this tells the compactor whether restarting the larger bucket operation is
+    // still appropriate.
+    // One exception is clock skew errors: We don't treat that as retryable by us,
+    // although the SDK may internally retry them.
+    return isThrottlingError(sdkError) || isTransientError(sdkError);
+}
+//# sourceMappingURL=S3ObjectStorage.js.map

package/dist/storage/implementation/v3/object-storage/S3ObjectStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"S3ObjectStorage.js","sourceRoot":"","sources":["../../../../../src/storage/implementation/v3/object-storage/S3ObjectStorage.ts"],"names":[],"mappings":"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"}

package/dist/types/types.d.ts

@@ -25,7 +25,42 @@ export declare const MongoStorageConfig: t.Intersection<t.Codec<{
      * This is an experimental option, and may be removed in a future release.
      */
     bulk_read_preference: t.OptionalCodec<t.Codec<"primary" | "primaryPreferred" | "secondary" | "secondaryPreferred" | "nearest", "primary" | "primaryPreferred" | "secondary" | "secondaryPreferred" | "nearest", string, t.CodecProps>>;
+    /**
+     * Throttle clear operations after sync config deploys, by pausing between batches.
+     * The rate produces a pause proportional to the previous batch duration.
+     *
+     * Increase this to reduce impact of clear operations on the storage cluster.
+     * Use 0 to clear as fast as possible.
+     *
+     * Defaults to 0.2.
+     */
+    clear_batch_throttle_rate: t.OptionalCodec<t.Codec<number, number, string, t.CodecProps>>;
+    object_storage: t.OptionalCodec<t.Codec<{
+        type: "s3";
+        bucket: string;
+        region?: string | undefined;
+        prefix?: string | undefined;
+        endpoint?: string | undefined;
+        force_path_style?: boolean | undefined;
+        access_key_id?: string | undefined;
+        secret_access_key?: string | undefined;
+        concurrency_limit?: number | undefined;
+        inline_threshold_bytes?: number | undefined;
+    }, {
+        type: "s3";
+        bucket: string;
+        region?: string | undefined;
+        prefix?: string | undefined;
+        endpoint?: string | undefined;
+        force_path_style?: boolean | undefined;
+        access_key_id?: string | undefined;
+        secret_access_key?: string | undefined;
+        concurrency_limit?: number | undefined;
+        inline_threshold_bytes?: number | undefined;
+    }, string, t.CodecProps>>;
 }>>;
 export type MongoStorageConfig = t.Encoded<typeof MongoStorageConfig>;
 export type MongoStorageConfigDecoded = t.Decoded<typeof MongoStorageConfig>;
+export declare const DEFAULT_CLEAR_BATCH_THROTTLE_RATE = 0.2;
+export declare function normalizeClearBatchThrottleRate(value: number | undefined): number;
 export declare function isMongoStorageConfig(config: service_types.configFile.GenericStorageConfig): config is MongoStorageConfig;

package/dist/types/types.js

@@ -1,5 +1,20 @@
 import * as lib_mongo from '@powersync/lib-service-mongodb';
+import { ErrorCode, ServiceError } from '@powersync/lib-services-framework';
 import * as t from 'ts-codec';
+const S3ObjectStorageConfig = t.object({
+    type: t.literal('s3'),
+    bucket: t.string,
+    region: t.string.optional(),
+    prefix: t.string.optional(),
+    endpoint: t.string.optional(),
+    force_path_style: t.boolean.optional(),
+    access_key_id: t.string.optional(),
+    secret_access_key: t.string.optional(),
+    concurrency_limit: t.number.optional(),
+    // Chunks whose BSON-serialized size falls below this byte threshold
+    // stay inline in MongoDB instead of being offloaded to S3. Default 1024.
+    inline_threshold_bytes: t.number.optional()
+});
 export const MongoStorageReadPreference = t
     .literal('primary')
     .or(t.literal('primaryPreferred'))
@@ -14,8 +29,27 @@ export const MongoStorageConfig = lib_mongo.BaseMongoConfig.and(t.object({
      *
      * This is an experimental option, and may be removed in a future release.
      */
-    bulk_read_preference: MongoStorageReadPreference.optional()
+    bulk_read_preference: MongoStorageReadPreference.optional(),
+    /**
+     * Throttle clear operations after sync config deploys, by pausing between batches.
+     * The rate produces a pause proportional to the previous batch duration.
+     *
+     * Increase this to reduce impact of clear operations on the storage cluster.
+     * Use 0 to clear as fast as possible.
+     *
+     * Defaults to 0.2.
+     */
+    clear_batch_throttle_rate: t.number.optional(),
+    object_storage: S3ObjectStorageConfig.optional()
 }));
+export const DEFAULT_CLEAR_BATCH_THROTTLE_RATE = 0.2;
+export function normalizeClearBatchThrottleRate(value) {
+    const rate = value ?? DEFAULT_CLEAR_BATCH_THROTTLE_RATE;
+    if (!Number.isFinite(rate) || rate < 0 || rate > 20) {
+        throw new ServiceError(ErrorCode.PSYNC_S3201, 'storage.clear_batch_throttle_rate must be a finite number between 0 and 20');
+    }
+    return rate;
+}
 export function isMongoStorageConfig(config) {
     return config.type == lib_mongo.MONGO_CONNECTION_TYPE;
 }