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

package/dist/replica-client.js

@@ -10,12 +10,92 @@
  *
  * Creation timestamps are preserved on upload as the `ltx-timestamp` object
  * metadata; listing falls back to the object's `LastModified`.
+ *
+ * The client also supports *fenced writes* (see {@link S3ReplicaClient.registerGeneration}).
+ * S3 cannot check one object and write another in a single request, so fencing
+ * is a protocol built from conditional writes:
+ *
+ * - `{prefix}/generation.json` holds the current generation and a list of
+ *   *fences*. A fence `(generation, txid)` records the latest TXID of the
+ *   replica right after `generation` was registered. Registering is a
+ *   conditional write (`If-Match` / `If-None-Match: *`) that only raises the
+ *   generation; the fence is then added with another conditional write.
+ * - LTX files of a fenced client are written with `If-None-Match: *`, so a TXID
+ *   range is written once per level, and carry their generation in the
+ *   `ltx-generation` metadata. A file with no `ltx-generation` is generation 0.
+ * - Listings ignore a file whose generation is lower than a fence's generation
+ *   and whose `maxTXID` is above that fence's TXID: it was written by a
+ *   superseded writer after the new one read the replica.
+ * - After each upload, a fenced client re-reads the generation object and fails
+ *   with {@link ErrGenerationSuperseded} if a higher generation is registered.
+ *   An upload that resolves was therefore written while its generation was the
+ *   latest, and every later generation sees it.
  */
 import { Readable } from 'node:stream';
 import { S3Client, AbortMultipartUploadCommand, CompleteMultipartUploadCommand, CreateMultipartUploadCommand, DeleteObjectsCommand, GetObjectCommand, HeadBucketCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand, UploadPartCommand, } from '@aws-sdk/client-s3';
-import { HeaderSize, LTXError, formatFilename, noopLogger, parseFilename, unmarshalHeader, } from '@platformatic/sqlite-js-stream';
+import { 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';
+/** Name of the generation object, relative to the replica prefix. */
+export const GenerationObjectName = 'generation.json';
+/** Object metadata key carrying the generation of a fenced LTX upload. */
+export const GenerationMetadataKey = 'ltx-generation';
+/**
+ * Returns true if a file of `generation` ending at `maxTXID` is part of the
+ * replica: no fence of a higher generation was recorded below `maxTXID`.
+ */
+export function isFenced(fences, generation, maxTXID) {
+    for (const f of fences) {
+        if (f.generation > generation && maxTXID > f.txid)
+            return false;
+    }
+    return true;
+}
+/** 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. */
+const HEAD_CONCURRENCY = 16;
+/** Cached generations of listed objects (by key and ETag). */
+const GENERATION_CACHE_SIZE = 10_000;
+/** Parses the `ltx-generation` metadata (0 when absent or invalid). */
+function metadataGeneration(metadata) {
+    const v = metadata?.[GenerationMetadataKey];
+    if (v === undefined || !/^\d+$/.test(v))
+        return 0n;
+    return BigInt(v);
+}
+/** Serializes a generation state (bigints as decimal strings). */
+function encodeGenerationState(state) {
+    return new TextEncoder().encode(JSON.stringify({
+        generation: state.generation.toString(),
+        fences: state.fences.map((f) => ({ generation: f.generation.toString(), txid: f.txid.toString() })),
+    }));
+}
+/** Parses a generation object body. */
+function decodeGenerationState(data) {
+    const parsed = JSON.parse(new TextDecoder().decode(data));
+    return {
+        generation: BigInt(parsed.generation ?? '0'),
+        fences: (parsed.fences ?? []).map((f) => ({
+            generation: BigInt(f.generation ?? '0'),
+            txid: BigInt(f.txid ?? '0'),
+        })),
+    };
+}
+/** Runs `fn` over `items` with at most `limit` calls in flight, preserving order. */
+async function mapLimit(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next++;
+            out[i] = await fn(items[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return out;
+}
 /** Normalized base prefix (no leading/trailing slash, `''` when empty). */
 function normalizePrefix(prefix) {
     return prefix.replace(/^\/+/, '').replace(/\/+$/, '');
@@ -41,12 +121,18 @@ export class S3ReplicaClient {
     prefix;
     client;
     logger = noopLogger;
+    generation;
+    /** The higher generation that superseded this client, once observed. */
+    supersededBy = null;
+    /** Generation of listed objects, keyed by `key` + ETag (objects are immutable). */
+    objectGenerations = new Map();
     constructor(opts) {
         if (!opts.bucket) {
             throw new Error('S3 replica client: bucket is required');
         }
         this.bucket = opts.bucket;
         this.prefix = normalizePrefix(opts.prefix ?? '');
+        this.generation = opts.generation ?? null;
         this.client =
             opts.client ??
                 new S3Client({
@@ -88,8 +174,169 @@ export class S3ReplicaClient {
     fileKey(level, minTXID, maxTXID) {
         return `${this.levelPrefix(level)}${formatFilename(minTXID, maxTXID)}`;
     }
+    /** Returns the key of the generation object. */
+    generationKey() {
+        return `${this.prefix ? `${this.prefix}/` : ''}${GenerationObjectName}`;
+    }
+    /** Current fenced-write generation, or `null` when fencing is disabled. */
+    getGeneration() {
+        return this.generation;
+    }
+    /** Reads the generation object, or returns `null` if fencing was never used. */
+    async getGenerationState() {
+        return (await this.readGenerationObject())?.state ?? null;
+    }
+    async readGenerationObject() {
+        let res;
+        try {
+            res = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: this.generationKey() }));
+        }
+        catch (err) {
+            if (isNotFound(err))
+                return null;
+            throw err;
+        }
+        const state = decodeGenerationState(await readBody(res.Body));
+        return { state, etag: String(res.ETag ?? '') };
+    }
+    /**
+     * Writes the generation object if it was not changed since it was read with
+     * `etag` (`null`: if it does not exist). Returns false on a lost race.
+     */
+    async writeGenerationObject(state, etag) {
+        try {
+            await this.client.send(new PutObjectCommand({
+                Bucket: this.bucket,
+                Key: this.generationKey(),
+                Body: encodeGenerationState(state),
+                ContentType: 'application/json',
+                ...(etag === null ? { IfNoneMatch: '*' } : { IfMatch: etag }),
+            }));
+            return true;
+        }
+        catch (err) {
+            if (isPreconditionFailed(err) || isConditionalConflict(err))
+                return false;
+            throw err;
+        }
+    }
+    /** Records that this client was superseded by `generation` and returns the error. */
+    superseded(generation) {
+        this.supersededBy = generation;
+        return new ErrGenerationSuperseded(generation);
+    }
+    /**
+     * Fails with {@link ErrGenerationSuperseded} if a generation higher than this
+     * client's is registered. A no-op when fencing is disabled.
+     */
+    async assertGeneration() {
+        if (this.generation === null)
+            return;
+        if (this.supersededBy !== null)
+            throw new ErrGenerationSuperseded(this.supersededBy);
+        const cur = await this.readGenerationObject();
+        if (cur !== null && cur.state.generation > this.generation) {
+            throw this.superseded(cur.state.generation);
+        }
+    }
+    /**
+     * Raises the replica's generation to `generation`, failing with
+     * {@link ErrGenerationSuperseded} if a higher one is already registered, and
+     * records a fence at the replica's latest TXID as read after the
+     * registration. From then on, files of lower generations above that TXID
+     * are ignored by every listing, and uploads and deletions of lower
+     * generations fail once they observe the new generation.
+     *
+     * Call it before restoring: the restore then sees every file that a former
+     * writer can still make part of the replica. Registering the current
+     * generation again is a no-op that keeps its fence.
+     */
+    async registerGeneration(generation) {
+        // 1. Raise the generation (compare-and-swap on the generation object).
+        for (let attempt = 0;; attempt++) {
+            if (attempt >= MAX_CONDITIONAL_ATTEMPTS) {
+                throw new Error('S3 replica client: too many conflicts registering the generation');
+            }
+            const cur = await this.readGenerationObject();
+            if (cur !== null && cur.state.generation > generation) {
+                throw new ErrGenerationSuperseded(cur.state.generation);
+            }
+            if (cur !== null && cur.state.generation === generation)
+                break;
+            const next = { generation, fences: cur?.state.fences ?? [] };
+            if (await this.writeGenerationObject(next, cur?.etag ?? null))
+                break;
+        }
+        this.generation = generation;
+        this.supersededBy = null;
+        // 2. Read the latest TXID of the replica. Files of lower generations that
+        //    land from now on and end above it are not part of the replica.
+        let txid = 0n;
+        for (let level = 0; level <= SnapshotLevel; level++) {
+            for await (const info of this.ltxFiles({ level, seek: 0n, useMetadata: false })) {
+                if (info.maxTXID > txid)
+                    txid = info.maxTXID;
+            }
+        }
+        // 3. Record the fence, unless a higher generation registered meanwhile.
+        for (let attempt = 0;; attempt++) {
+            if (attempt >= MAX_CONDITIONAL_ATTEMPTS) {
+                throw new Error('S3 replica client: too many conflicts recording the generation fence');
+            }
+            const cur = await this.readGenerationObject();
+            const stored = cur?.state.generation ?? generation;
+            if (stored > generation)
+                throw this.superseded(stored);
+            const fences = cur?.state.fences ?? [];
+            if (fences.some((f) => f.generation === generation))
+                break;
+            const next = { generation, fences: [...fences, { generation, txid }] };
+            if (await this.writeGenerationObject(next, cur?.etag ?? null))
+                break;
+        }
+        this.logger.debug('registered generation', { generation, txid });
+    }
+    /** Returns the generation of an object (from `ltx-generation`), or null if it is gone. */
+    async objectGeneration(key, etag) {
+        const cacheKey = etag ? `${key}\n${etag}` : null;
+        if (cacheKey !== null) {
+            const cached = this.objectGenerations.get(cacheKey);
+            if (cached !== undefined)
+                return cached;
+        }
+        let head;
+        try {
+            head = await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: key }));
+        }
+        catch (err) {
+            if (isNotFound(err))
+                return null;
+            throw err;
+        }
+        const generation = metadataGeneration(head.Metadata);
+        this.rememberGeneration(key, head.ETag ?? etag, generation);
+        return generation;
+    }
+    rememberGeneration(key, etag, generation) {
+        if (!etag)
+            return;
+        if (this.objectGenerations.size >= GENERATION_CACHE_SIZE)
+            this.objectGenerations.clear();
+        this.objectGenerations.set(`${key}\n${etag}`, generation);
+    }
+    /**
+     * Lists the LTX files of a level. When the replica has fences, files ending
+     * above the lowest fence need their generation (a HeadObject request, cached
+     * per key and ETag), and those written by a superseded writer are skipped.
+     */
     async *ltxFiles(opts) {
         const prefix = this.levelPrefix(opts.level);
+        const fences = (await this.readGenerationObject())?.state.fences ?? [];
+        let lowestFence = null;
+        for (const f of fences) {
+            if (lowestFence === null || f.txid < lowestFence)
+                lowestFence = f.txid;
+        }
         let token;
         do {
             const res = await this.client.send(new ListObjectsV2Command({
@@ -97,6 +344,7 @@ export class S3ReplicaClient {
                 Prefix: prefix,
                 ContinuationToken: token,
             }));
+            const page = [];
             for (const obj of res.Contents ?? []) {
                 if (!obj.Key)
                     continue;
@@ -111,13 +359,31 @@ export class S3ReplicaClient {
                 }
                 if (minTXID < opts.seek)
                     continue;
-                yield {
-                    level: opts.level,
-                    minTXID,
-                    maxTXID,
-                    size: obj.Size ?? 0,
-                    createdAt: (obj.LastModified ?? new Date(0)).getTime(),
-                };
+                page.push({
+                    key: obj.Key,
+                    etag: obj.ETag,
+                    info: {
+                        level: opts.level,
+                        minTXID,
+                        maxTXID,
+                        size: obj.Size ?? 0,
+                        createdAt: (obj.LastModified ?? new Date(0)).getTime(),
+                    },
+                });
+            }
+            let visible = page.map(() => true);
+            if (lowestFence !== null) {
+                const fence = lowestFence;
+                visible = await mapLimit(page, HEAD_CONCURRENCY, async (p) => {
+                    if (p.info.maxTXID <= fence)
+                        return true;
+                    const generation = await this.objectGeneration(p.key, p.etag);
+                    return generation !== null && isFenced(fences, generation, p.info.maxTXID);
+                });
+            }
+            for (let i = 0; i < page.length; i++) {
+                if (visible[i])
+                    yield page[i].info;
             }
             token = res.IsTruncated ? (res.NextContinuationToken ?? undefined) : undefined;
         } while (token);
@@ -162,6 +428,10 @@ export class S3ReplicaClient {
     }
     async writeLtxFile(opts, body) {
         const key = this.fileKey(opts.level, opts.minTXID, opts.maxTXID);
+        const generation = this.generation;
+        if (generation !== null && this.supersededBy !== null) {
+            throw new ErrGenerationSuperseded(this.supersededBy);
+        }
         // Capture the LTX header (timestamp) from the leading bytes, and stream the
         // rest. Small objects use a single PutObject; large objects (> 5 MiB) are
         // uploaded with the multipart API so the whole file is never buffered.
@@ -172,6 +442,7 @@ export class S3ReplicaClient {
         let accLen = 0;
         let size = 0;
         let uploadId = null;
+        let completed = false;
         let partNumber = 0;
         const uploadedParts = [];
         const uploadPart = async (buf) => {
@@ -185,6 +456,12 @@ export class S3ReplicaClient {
             }));
             uploadedParts.push({ PartNumber: partNumber, ETag: res.ETag ?? `etag-${partNumber}` });
         };
+        const metadataFor = (timestamp) => {
+            const metadata = { 'ltx-timestamp': String(timestamp) };
+            if (generation !== null)
+                metadata[GenerationMetadataKey] = generation.toString();
+            return metadata;
+        };
         try {
             for await (const chunk of body) {
                 const bytes = typeof chunk === 'string' ? new TextEncoder().encode(chunk) : Uint8Array.from(chunk);
@@ -206,7 +483,7 @@ export class S3ReplicaClient {
                     const res = await this.client.send(new CreateMultipartUploadCommand({
                         Bucket: this.bucket,
                         Key: key,
-                        Metadata: { 'ltx-timestamp': String(Number(unmarshalHeader(headerBytes).timestamp)) },
+                        Metadata: metadataFor(Number(unmarshalHeader(headerBytes).timestamp)),
                     }));
                     uploadId = res.UploadId;
                     await uploadPart(concatBytes(acc));
@@ -223,39 +500,62 @@ export class S3ReplicaClient {
                 throw new Error('write ltx file: input too short to contain a header');
             }
             const timestamp = Number(unmarshalHeader(headerBytes).timestamp);
-            const metadata = { 'ltx-timestamp': String(timestamp) };
-            if (uploadId === null) {
-                // Single PutObject for small objects.
-                const buf = concatBytes(acc);
-                await this.client.send(new PutObjectCommand({
-                    Bucket: this.bucket,
-                    Key: key,
-                    Body: buf,
-                    ContentLength: size,
-                    Metadata: metadata,
-                }));
+            // Multipart: upload any remaining bytes as the final part.
+            if (uploadId !== null && accLen > 0) {
+                await uploadPart(concatBytes(acc));
+                acc = [];
+                accLen = 0;
             }
-            else {
-                // Multipart: upload any remaining bytes as the final part, then complete.
-                if (accLen > 0)
-                    await uploadPart(concatBytes(acc));
-                await this.client.send(new CompleteMultipartUploadCommand({
+            const buf = uploadId === null ? concatBytes(acc) : null;
+            // Creates the object: a single PutObject for small objects, otherwise
+            // completes the multipart upload.
+            const commit = (condition) => {
+                if (buf !== null) {
+                    return this.client.send(new PutObjectCommand({
+                        Bucket: this.bucket,
+                        Key: key,
+                        Body: buf,
+                        ContentLength: size,
+                        Metadata: metadataFor(timestamp),
+                        ...condition,
+                    }));
+                }
+                return this.client.send(new CompleteMultipartUploadCommand({
                     Bucket: this.bucket,
                     Key: key,
                     UploadId: uploadId,
                     MultipartUpload: { Parts: uploadedParts },
+                    ...condition,
                 }));
-            }
-            return {
+            };
+            const info = {
                 level: opts.level,
                 minTXID: opts.minTXID,
                 maxTXID: opts.maxTXID,
                 size,
                 createdAt: timestamp,
             };
+            if (generation === null) {
+                await commit({});
+                completed = true;
+                return info;
+            }
+            // A multipart upload first looks for an existing object, so that the
+            // completion is not expected to fail (S3 may not keep the upload open).
+            const existing = await this.commitFenced(key, opts, generation, commit, uploadId !== null);
+            completed = existing === null;
+            // The upload is only acknowledged if this generation is still the latest
+            // after it landed: any generation registered later then sees the file.
+            await this.assertGeneration();
+            return existing ?? info;
         }
         catch (err) {
-            if (uploadId !== null) {
+            if (err instanceof ErrGenerationSuperseded)
+                throw err;
+            throw new LTXError('write', key, opts.level, opts.minTXID, opts.maxTXID, err);
+        }
+        finally {
+            if (uploadId !== null && !completed) {
                 await this.client
                     .send(new AbortMultipartUploadCommand({
                     Bucket: this.bucket,
@@ -264,28 +564,102 @@ export class S3ReplicaClient {
                 }))
                     .catch(() => { });
             }
-            throw new LTXError('write', key, opts.level, opts.minTXID, opts.maxTXID, err);
         }
     }
+    /**
+     * Creates a fenced LTX object with `If-None-Match: *`. If the key already
+     * exists:
+     *  - written by a higher generation: this client is superseded;
+     *  - written by this generation (a retried upload), or by a lower one but
+     *    still part of the replica: it holds the same transactions, so it is
+     *    kept and its metadata returned;
+     *  - otherwise it is a superseded writer's file, replaced with `If-Match`.
+     * With `probe`, the key is checked with HeadObject before the first write.
+     * Returns null when this call created the object.
+     */
+    async commitFenced(key, opts, generation, commit, probe) {
+        let condition = { IfNoneMatch: '*' };
+        for (let attempt = 0; attempt < MAX_CONDITIONAL_ATTEMPTS; attempt++) {
+            if (!probe) {
+                try {
+                    const res = await commit(condition);
+                    this.rememberGeneration(key, res.ETag, generation);
+                    return null;
+                }
+                catch (err) {
+                    if (isConditionalConflict(err))
+                        continue;
+                    if (!isPreconditionFailed(err))
+                        throw err;
+                }
+            }
+            probe = false;
+            let head;
+            try {
+                head = await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: key }));
+            }
+            catch (err) {
+                if (isNotFound(err)) {
+                    condition = { IfNoneMatch: '*' }; // deleted meanwhile
+                    continue;
+                }
+                throw err;
+            }
+            const existing = metadataGeneration(head.Metadata);
+            if (existing > generation)
+                throw this.superseded(existing);
+            const fences = (await this.readGenerationObject())?.state.fences ?? [];
+            if (existing === generation || isFenced(fences, existing, opts.maxTXID)) {
+                const timestamp = Number(head.Metadata?.['ltx-timestamp']);
+                return {
+                    level: opts.level,
+                    minTXID: opts.minTXID,
+                    maxTXID: opts.maxTXID,
+                    size: Number(head.ContentLength ?? 0),
+                    createdAt: Number.isFinite(timestamp)
+                        ? timestamp
+                        : (head.LastModified ?? new Date(0)).getTime(),
+                };
+            }
+            this.logger.debug('replacing ltx file of a superseded writer', { key, generation: existing });
+            condition = { IfMatch: String(head.ETag ?? '') };
+        }
+        throw new Error(`too many conflicting writes to ${key}`);
+    }
+    /**
+     * Deletes LTX files. A fenced client first checks that its generation is
+     * still the latest and fails with {@link ErrGenerationSuperseded} otherwise
+     * (a deletion sent just before a new generation registers still applies).
+     */
     async deleteLtxFiles(infos) {
         const objects = infos.map((info) => ({
             Key: this.fileKey(info.level, info.minTXID, info.maxTXID),
         }));
         for (let i = 0; i < objects.length; i += 1000) {
+            await this.assertGeneration();
             await this.client.send(new DeleteObjectsCommand({
                 Bucket: this.bucket,
                 Delete: { Objects: objects.slice(i, i + 1000), Quiet: true },
             }));
         }
     }
+    /**
+     * Deletes every object under the prefix except the generation object, so a
+     * superseded writer stays fenced. A fenced client checks its generation
+     * first, as {@link deleteLtxFiles} does.
+     */
     async deleteAll() {
         const prefix = this.prefix ? `${this.prefix}/` : '';
+        const generationKey = this.generationKey();
         let token;
         do {
             const res = await this.client.send(new ListObjectsV2Command({ Bucket: this.bucket, Prefix: prefix, ContinuationToken: token }));
             const contents = (res.Contents ?? []);
-            const objects = contents.filter((o) => o.Key).map((o) => ({ Key: o.Key }));
+            const objects = contents
+                .filter((o) => o.Key && o.Key !== generationKey)
+                .map((o) => ({ Key: o.Key }));
             for (let i = 0; i < objects.length; i += 1000) {
+                await this.assertGeneration();
                 await this.client.send(new DeleteObjectsCommand({
                     Bucket: this.bucket,
                     Delete: { Objects: objects.slice(i, i + 1000), Quiet: true },

package/dist/util.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Helpers shared by the S3 replica client and leaser: body reading and the
+ * classification of S3 errors (404, 412, 409).
+ */
+/** Reads all bytes from an S3 body (stream or Buffer). */
+export declare function readBody(body: any): Promise<Uint8Array>;
+export declare function isPreconditionFailed(err: unknown): boolean;
+export declare function isNotFound(err: unknown): boolean;
+/**
+ * A concurrent conditional write to the same key (`409 ConditionalRequestConflict`).
+ * S3 asks the caller to retry the request.
+ */
+export declare function isConditionalConflict(err: unknown): boolean;
+//# sourceMappingURL=util.d.ts.map

package/dist/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,0DAA0D;AAC1D,wBAAsB,QAAQ,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC,CAuC7D;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAI1D;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAIhD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAI3D"}

package/dist/util.js

@@ -0,0 +1,68 @@
+/**
+ * Helpers shared by the S3 replica client and leaser: body reading and the
+ * classification of S3 errors (404, 412, 409).
+ */
+/** Reads all bytes from an S3 body (stream or Buffer). */
+export async function readBody(body) {
+    // AWS SDK v3 returns a mix; normalize to a Uint8Array.
+    if (body instanceof Uint8Array)
+        return body;
+    if (typeof body?.on === 'function') {
+        // Node stream.
+        const chunks = [];
+        for await (const chunk of body) {
+            chunks.push(typeof chunk === 'string' ? new TextEncoder().encode(chunk) : chunk);
+        }
+        let total = 0;
+        for (const c of chunks)
+            total += c.length;
+        const out = new Uint8Array(total);
+        let o = 0;
+        for (const c of chunks) {
+            out.set(c, o);
+            o += c.length;
+        }
+        return out;
+    }
+    // Web ReadableStream or Buffer.
+    if (typeof body?.getReader === 'function') {
+        const reader = body.getReader();
+        const chunks = [];
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            chunks.push(value);
+        }
+        let total = 0;
+        for (const c of chunks)
+            total += c.length;
+        const out = new Uint8Array(total);
+        let o = 0;
+        for (const c of chunks) {
+            out.set(c, o);
+            o += c.length;
+        }
+        return out;
+    }
+    return new Uint8Array(body);
+}
+export function isPreconditionFailed(err) {
+    const code = err?.$metadata?.httpStatusCode;
+    const name = err?.name ?? '';
+    return code === 412 || name === 'PreconditionFailed';
+}
+export function isNotFound(err) {
+    const code = err?.$metadata?.httpStatusCode;
+    const name = err?.name ?? '';
+    return code === 404 || name === 'NoSuchKey' || name === 'NotFound';
+}
+/**
+ * A concurrent conditional write to the same key (`409 ConditionalRequestConflict`).
+ * S3 asks the caller to retry the request.
+ */
+export function isConditionalConflict(err) {
+    const code = err?.$metadata?.httpStatusCode;
+    const name = err?.name ?? '';
+    return code === 409 || name === 'ConditionalRequestConflict';
+}

package/package.json

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

package/src/index.ts

@@ -9,7 +9,12 @@
 export {
   S3ReplicaClient,
   newReplicaClientFromURL,
+  isFenced,
+  GenerationMetadataKey,
+  GenerationObjectName,
   ReplicaClientType,
+  type GenerationFence,
+  type GenerationState,
   type S3ClientLike,
   type S3ReplicaClientOptions,
 } from './replica-client.ts';