@platformatic/sqlite-js-stream-s3 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -5,6 +5,6 @@
  * factory, so `newReplicaClientFromURL('s3://bucket/prefix')` resolves after
  * this addon is loaded.
  */
-export { S3ReplicaClient, newReplicaClientFromURL, isFenced, GenerationMetadataKey, GenerationObjectName, ReplicaClientType, type GenerationFence, type GenerationState, type S3ClientLike, type S3ReplicaClientOptions, } from './replica-client.ts';
+export { S3ReplicaClient, newReplicaClientFromURL, isFenced, GenerationMetadataKey, GenerationObjectName, ReplicaClientType, type GenerationFence, type GenerationState, type S3ClientLike, type S3DeletePrefixOptions, type S3ReplicaClientOptions, } from './replica-client.ts';
 export { S3Leaser } from './leaser.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,QAAQ,EACR,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,sBAAsB,GAC5B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,QAAQ,EACR,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC"}

package/dist/replica-client.d.ts

@@ -65,6 +65,33 @@ export interface S3ReplicaClientOptions {
      */
     generation?: bigint | null;
 }
+/** Configuration for {@link S3ReplicaClient.deletePrefix}. */
+export interface S3DeletePrefixOptions {
+    /** S3 bucket name. Required. */
+    bucket: string;
+    /**
+     * Prefix to delete: the replica at this prefix and every replica under
+     * `prefix/` (`a` covers `a` and `a/b`, not `ab`). Leading/trailing slashes
+     * are normalized away. Must not be empty.
+     */
+    prefix: string;
+    /** AWS region. Defaults to the AWS SDK region resolution chain. */
+    region?: string;
+    /** Custom endpoint URL (e.g. for MinIO / LocalStack). */
+    endpoint?: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    sessionToken?: string;
+    /** Inject a preconfigured client. */
+    client?: S3ClientLike;
+    /**
+     * Fences the deletion: it fails with {@link ErrGenerationSuperseded} if a
+     * replica under the prefix has a higher generation, checked before deleting
+     * any of its objects (best effort, see {@link S3ReplicaClient.deletePrefix}).
+     * `null` (the default) deletes unconditionally.
+     */
+    generation?: bigint | null;
+}
 /** Name of the generation object, relative to the replica prefix. */
 export declare const GenerationObjectName = "generation.json";
 /** Object metadata key carrying the generation of a fenced LTX upload. */
@@ -172,6 +199,29 @@ export declare class S3ReplicaClient implements ReplicaClient {
      * (a deletion sent just before a new generation registers still applies).
      */
     deleteLtxFiles(infos: FileInfo[]): Promise<void>;
+    /**
+     * Deletes every replica under a prefix: every object whose key starts with
+     * `prefix/`, which covers the replica at `prefix` and every replica under
+     * it, generation objects (`generation.json`) and lease objects included
+     * (unlike {@link deleteAll}, which keeps the generation). Resolves with the
+     * sorted prefixes of the deleted replicas: those with an LTX file, a
+     * generation object or a lease object.
+     *
+     * The generation objects are deleted last, so former writers stay fenced
+     * while the files are deleted. Once they are gone, nothing fences those
+     * writers anymore: a writer that is still running can upload again and
+     * create the replica anew. Stop the writers first.
+     *
+     * With {@link S3DeletePrefixOptions.generation}, the deletion is fenced as
+     * the deletions of a fenced client are, on a best-effort basis: the
+     * generation object of each replica is read before deleting its first
+     * object, and again before deleting the generation objects, and the
+     * deletion fails with {@link ErrGenerationSuperseded} if it holds a higher
+     * generation. S3 cannot check one object and delete another atomically, so
+     * a generation registered between a check and a `DeleteObjects` request
+     * does not stop it, and the replicas already processed stay deleted.
+     */
+    static deletePrefix(opts: S3DeletePrefixOptions): Promise<string[]>;
     /**
      * Deletes every object under the prefix except the generation object, so a
      * superseded writer stays fenced. A fenced client checks its generation

package/dist/replica-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replica-client.d.ts","sourceRoot":"","sources":["../src/replica-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"replica-client.d.ts","sourceRoot":"","sources":["../src/replica-client.ts"],"names":[],"mappings":"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"}

package/dist/replica-client.js

@@ -33,7 +33,7 @@
  */
 import { Readable } from 'node:stream';
 import { S3Client, AbortMultipartUploadCommand, CompleteMultipartUploadCommand, CreateMultipartUploadCommand, DeleteObjectsCommand, GetObjectCommand, HeadBucketCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand, UploadPartCommand, } from '@aws-sdk/client-s3';
-import { ErrGenerationSuperseded, HeaderSize, LTXError, SnapshotLevel, formatFilename, noopLogger, parseFilename, unmarshalHeader, } from '@platformatic/sqlite-js-stream';
+import { DefaultLeasePath, ErrGenerationSuperseded, HeaderSize, LTXError, SnapshotLevel, formatFilename, noopLogger, parseFilename, unmarshalHeader, } from '@platformatic/sqlite-js-stream';
 import { isConditionalConflict, isNotFound, isPreconditionFailed, readBody } from "./util.js";
 /** The strategy identifier reported by {@link S3ReplicaClient.type}. */
 export const ReplicaClientType = 's3';
@@ -52,6 +52,31 @@ export function isFenced(fences, generation, maxTXID) {
     }
     return true;
 }
+/** Matches the key of an LTX file, capturing the prefix of its replica. */
+const LTX_KEY_RE = /^(.+)\/ltx\/\d+\/[^/]+$/;
+/** Returns the prefix of the replica a key belongs to, or null if none. */
+function replicaOfKey(key) {
+    for (const name of [GenerationObjectName, DefaultLeasePath]) {
+        if (key.endsWith(`/${name}`))
+            return key.slice(0, -(name.length + 1));
+    }
+    return LTX_KEY_RE.exec(key)?.[1] ?? null;
+}
+/** Builds an S3 client from connection options, unless one is injected. */
+function createClient(opts) {
+    return (opts.client ??
+        new S3Client({
+            region: opts.region,
+            endpoint: opts.endpoint,
+            credentials: opts.accessKeyId
+                ? {
+                    accessKeyId: opts.accessKeyId,
+                    secretAccessKey: opts.secretAccessKey ?? '',
+                    sessionToken: opts.sessionToken,
+                }
+                : undefined,
+        }));
+}
 /** Retries of a conditional write that keeps conflicting with concurrent ones. */
 const MAX_CONDITIONAL_ATTEMPTS = 10;
 /** HeadObject requests in flight while resolving the generation of listed files. */
@@ -133,19 +158,7 @@ export class S3ReplicaClient {
         this.bucket = opts.bucket;
         this.prefix = normalizePrefix(opts.prefix ?? '');
         this.generation = opts.generation ?? null;
-        this.client =
-            opts.client ??
-                new S3Client({
-                    region: opts.region,
-                    endpoint: opts.endpoint,
-                    credentials: opts.accessKeyId
-                        ? {
-                            accessKeyId: opts.accessKeyId,
-                            secretAccessKey: opts.secretAccessKey ?? '',
-                            sessionToken: opts.sessionToken,
-                        }
-                        : undefined,
-                });
+        this.client = createClient(opts);
     }
     type() {
         return ReplicaClientType;
@@ -643,6 +656,113 @@ export class S3ReplicaClient {
             }));
         }
     }
+    /**
+     * Deletes every replica under a prefix: every object whose key starts with
+     * `prefix/`, which covers the replica at `prefix` and every replica under
+     * it, generation objects (`generation.json`) and lease objects included
+     * (unlike {@link deleteAll}, which keeps the generation). Resolves with the
+     * sorted prefixes of the deleted replicas: those with an LTX file, a
+     * generation object or a lease object.
+     *
+     * The generation objects are deleted last, so former writers stay fenced
+     * while the files are deleted. Once they are gone, nothing fences those
+     * writers anymore: a writer that is still running can upload again and
+     * create the replica anew. Stop the writers first.
+     *
+     * With {@link S3DeletePrefixOptions.generation}, the deletion is fenced as
+     * the deletions of a fenced client are, on a best-effort basis: the
+     * generation object of each replica is read before deleting its first
+     * object, and again before deleting the generation objects, and the
+     * deletion fails with {@link ErrGenerationSuperseded} if it holds a higher
+     * generation. S3 cannot check one object and delete another atomically, so
+     * a generation registered between a check and a `DeleteObjects` request
+     * does not stop it, and the replicas already processed stay deleted.
+     */
+    static async deletePrefix(opts) {
+        if (!opts.bucket) {
+            throw new Error('S3 replica client: bucket is required');
+        }
+        const prefix = normalizePrefix(opts.prefix ?? '');
+        if (prefix === '') {
+            throw new Error('S3 replica client: deletePrefix requires a non-empty prefix');
+        }
+        const bucket = opts.bucket;
+        const generation = opts.generation ?? null;
+        const ownClient = opts.client === undefined;
+        const client = createClient(opts);
+        const replicas = new Set();
+        const checked = new Set();
+        const generationKeys = [];
+        let pending = [];
+        const assertReplica = async (replica) => {
+            if (generation === null)
+                return;
+            let res;
+            try {
+                res = await client.send(new GetObjectCommand({ Bucket: bucket, Key: `${replica}/${GenerationObjectName}` }));
+            }
+            catch (err) {
+                if (isNotFound(err))
+                    return;
+                throw err;
+            }
+            const stored = decodeGenerationState(await readBody(res.Body)).generation;
+            if (stored > generation)
+                throw new ErrGenerationSuperseded(stored);
+        };
+        const flush = async (objects) => {
+            for (let i = 0; i < objects.length; i += 1000) {
+                const res = await client.send(new DeleteObjectsCommand({
+                    Bucket: bucket,
+                    Delete: { Objects: objects.slice(i, i + 1000), Quiet: true },
+                }));
+                const failed = (res?.Errors ?? []);
+                if (failed.length > 0) {
+                    const e = failed[0];
+                    throw new Error(`S3 replica client: failed to delete ${e.Key}: ${e.Code ?? ''} ${e.Message ?? ''}`.trim());
+                }
+            }
+        };
+        try {
+            let token;
+            do {
+                const res = await client.send(new ListObjectsV2Command({ Bucket: bucket, Prefix: `${prefix}/`, ContinuationToken: token }));
+                for (const obj of (res.Contents ?? [])) {
+                    const key = obj.Key;
+                    if (!key)
+                        continue;
+                    const replica = replicaOfKey(key);
+                    if (replica !== null) {
+                        replicas.add(replica);
+                        if (!checked.has(replica)) {
+                            await assertReplica(replica);
+                            checked.add(replica);
+                        }
+                    }
+                    if (key.endsWith(`/${GenerationObjectName}`)) {
+                        generationKeys.push(key);
+                        continue;
+                    }
+                    pending.push({ Key: key });
+                    if (pending.length >= 1000) {
+                        await flush(pending);
+                        pending = [];
+                    }
+                }
+                token = res.IsTruncated ? (res.NextContinuationToken ?? undefined) : undefined;
+            } while (token);
+            await flush(pending);
+            for (const key of generationKeys) {
+                await assertReplica(key.slice(0, -(GenerationObjectName.length + 1)));
+            }
+            await flush(generationKeys.map((Key) => ({ Key })));
+        }
+        finally {
+            if (ownClient)
+                client.destroy();
+        }
+        return [...replicas].sort();
+    }
     /**
      * Deletes every object under the prefix except the generation object, so a
      * superseded writer stays fenced. A fenced client checks its generation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/sqlite-js-stream-s3",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Amazon S3 upload strategy (replica client) for @platformatic/sqlite-js-stream",
   "type": "module",
   "engines": {
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1135.0",
-    "@platformatic/sqlite-js-stream": "0.3.0"
+    "@platformatic/sqlite-js-stream": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",

package/src/index.ts

@@ -16,6 +16,7 @@ export {
   type GenerationFence,
   type GenerationState,
   type S3ClientLike,
+  type S3DeletePrefixOptions,
   type S3ReplicaClientOptions,
 } from './replica-client.ts';
 

package/src/replica-client.ts

@@ -49,6 +49,7 @@ import {
 } from '@aws-sdk/client-s3';
 
 import {
+  DefaultLeasePath,
   ErrGenerationSuperseded,
   HeaderSize,
   LTXError,
@@ -102,6 +103,34 @@ export interface S3ReplicaClientOptions {
   generation?: bigint | null;
 }
 
+/** Configuration for {@link S3ReplicaClient.deletePrefix}. */
+export interface S3DeletePrefixOptions {
+  /** S3 bucket name. Required. */
+  bucket: string;
+  /**
+   * Prefix to delete: the replica at this prefix and every replica under
+   * `prefix/` (`a` covers `a` and `a/b`, not `ab`). Leading/trailing slashes
+   * are normalized away. Must not be empty.
+   */
+  prefix: string;
+  /** AWS region. Defaults to the AWS SDK region resolution chain. */
+  region?: string;
+  /** Custom endpoint URL (e.g. for MinIO / LocalStack). */
+  endpoint?: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  sessionToken?: string;
+  /** Inject a preconfigured client. */
+  client?: S3ClientLike;
+  /**
+   * Fences the deletion: it fails with {@link ErrGenerationSuperseded} if a
+   * replica under the prefix has a higher generation, checked before deleting
+   * any of its objects (best effort, see {@link S3ReplicaClient.deletePrefix}).
+   * `null` (the default) deletes unconditionally.
+   */
+  generation?: bigint | null;
+}
+
 /** Name of the generation object, relative to the replica prefix. */
 export const GenerationObjectName = 'generation.json';
 
@@ -136,6 +165,42 @@ export function isFenced(fences: readonly GenerationFence[], generation: bigint,
   return true;
 }
 
+/** Matches the key of an LTX file, capturing the prefix of its replica. */
+const LTX_KEY_RE = /^(.+)\/ltx\/\d+\/[^/]+$/;
+
+/** Returns the prefix of the replica a key belongs to, or null if none. */
+function replicaOfKey(key: string): string | null {
+  for (const name of [GenerationObjectName, DefaultLeasePath]) {
+    if (key.endsWith(`/${name}`)) return key.slice(0, -(name.length + 1));
+  }
+  return LTX_KEY_RE.exec(key)?.[1] ?? null;
+}
+
+/** Builds an S3 client from connection options, unless one is injected. */
+function createClient(opts: {
+  client?: S3ClientLike;
+  region?: string;
+  endpoint?: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  sessionToken?: string;
+}): S3ClientLike {
+  return (
+    opts.client ??
+    new S3Client({
+      region: opts.region,
+      endpoint: opts.endpoint,
+      credentials: opts.accessKeyId
+        ? {
+            accessKeyId: opts.accessKeyId,
+            secretAccessKey: opts.secretAccessKey ?? '',
+            sessionToken: opts.sessionToken,
+          }
+        : undefined,
+    })
+  );
+}
+
 /** Retries of a conditional write that keeps conflicting with concurrent ones. */
 const MAX_CONDITIONAL_ATTEMPTS = 10;
 
@@ -234,19 +299,7 @@ export class S3ReplicaClient implements ReplicaClient {
     this.bucket = opts.bucket;
     this.prefix = normalizePrefix(opts.prefix ?? '');
     this.generation = opts.generation ?? null;
-    this.client =
-      opts.client ??
-      new S3Client({
-        region: opts.region,
-        endpoint: opts.endpoint,
-        credentials: opts.accessKeyId
-          ? {
-              accessKeyId: opts.accessKeyId,
-              secretAccessKey: opts.secretAccessKey ?? '',
-              sessionToken: opts.sessionToken,
-            }
-          : undefined,
-      });
+    this.client = createClient(opts);
   }
 
   type(): string {
@@ -776,6 +829,118 @@ export class S3ReplicaClient implements ReplicaClient {
     }
   }
 
+  /**
+   * Deletes every replica under a prefix: every object whose key starts with
+   * `prefix/`, which covers the replica at `prefix` and every replica under
+   * it, generation objects (`generation.json`) and lease objects included
+   * (unlike {@link deleteAll}, which keeps the generation). Resolves with the
+   * sorted prefixes of the deleted replicas: those with an LTX file, a
+   * generation object or a lease object.
+   *
+   * The generation objects are deleted last, so former writers stay fenced
+   * while the files are deleted. Once they are gone, nothing fences those
+   * writers anymore: a writer that is still running can upload again and
+   * create the replica anew. Stop the writers first.
+   *
+   * With {@link S3DeletePrefixOptions.generation}, the deletion is fenced as
+   * the deletions of a fenced client are, on a best-effort basis: the
+   * generation object of each replica is read before deleting its first
+   * object, and again before deleting the generation objects, and the
+   * deletion fails with {@link ErrGenerationSuperseded} if it holds a higher
+   * generation. S3 cannot check one object and delete another atomically, so
+   * a generation registered between a check and a `DeleteObjects` request
+   * does not stop it, and the replicas already processed stay deleted.
+   */
+  static async deletePrefix(opts: S3DeletePrefixOptions): Promise<string[]> {
+    if (!opts.bucket) {
+      throw new Error('S3 replica client: bucket is required');
+    }
+    const prefix = normalizePrefix(opts.prefix ?? '');
+    if (prefix === '') {
+      throw new Error('S3 replica client: deletePrefix requires a non-empty prefix');
+    }
+    const bucket = opts.bucket;
+    const generation = opts.generation ?? null;
+    const ownClient = opts.client === undefined;
+    const client = createClient(opts);
+
+    const replicas = new Set<string>();
+    const checked = new Set<string>();
+    const generationKeys: string[] = [];
+    let pending: Array<{ Key: string }> = [];
+
+    const assertReplica = async (replica: string): Promise<void> => {
+      if (generation === null) return;
+      let res;
+      try {
+        res = await client.send(
+          new GetObjectCommand({ Bucket: bucket, Key: `${replica}/${GenerationObjectName}` }),
+        );
+      } catch (err) {
+        if (isNotFound(err)) return;
+        throw err;
+      }
+      const stored = decodeGenerationState(await readBody(res.Body)).generation;
+      if (stored > generation) throw new ErrGenerationSuperseded(stored);
+    };
+
+    const flush = async (objects: Array<{ Key: string }>): Promise<void> => {
+      for (let i = 0; i < objects.length; i += 1000) {
+        const res = await client.send(
+          new DeleteObjectsCommand({
+            Bucket: bucket,
+            Delete: { Objects: objects.slice(i, i + 1000), Quiet: true },
+          }),
+        );
+        const failed = (res?.Errors ?? []) as Array<{ Key?: string; Code?: string; Message?: string }>;
+        if (failed.length > 0) {
+          const e = failed[0];
+          throw new Error(`S3 replica client: failed to delete ${e.Key}: ${e.Code ?? ''} ${e.Message ?? ''}`.trim());
+        }
+      }
+    };
+
+    try {
+      let token: string | undefined;
+      do {
+        const res = await client.send(
+          new ListObjectsV2Command({ Bucket: bucket, Prefix: `${prefix}/`, ContinuationToken: token }),
+        );
+        for (const obj of (res.Contents ?? []) as Array<{ Key?: string }>) {
+          const key = obj.Key;
+          if (!key) continue;
+          const replica = replicaOfKey(key);
+          if (replica !== null) {
+            replicas.add(replica);
+            if (!checked.has(replica)) {
+              await assertReplica(replica);
+              checked.add(replica);
+            }
+          }
+          if (key.endsWith(`/${GenerationObjectName}`)) {
+            generationKeys.push(key);
+            continue;
+          }
+          pending.push({ Key: key });
+          if (pending.length >= 1000) {
+            await flush(pending);
+            pending = [];
+          }
+        }
+        token = res.IsTruncated ? (res.NextContinuationToken ?? undefined) : undefined;
+      } while (token);
+      await flush(pending);
+
+      for (const key of generationKeys) {
+        await assertReplica(key.slice(0, -(GenerationObjectName.length + 1)));
+      }
+      await flush(generationKeys.map((Key) => ({ Key })));
+    } finally {
+      if (ownClient) (client as S3Client).destroy();
+    }
+    return [...replicas].sort();
+  }
+
   /**
    * Deletes every object under the prefix except the generation object, so a
    * superseded writer stays fenced. A fenced client checks its generation