@cloudbitmaps/s3 0.11.1 → 0.12.0

package/dist/index.js

@@ -1,18 +1,18 @@
 // src/backend.ts
-import { ValidationError as ValidationError3, brandAsBackend } from "@cloudbitmaps/core/driver-kit";
+import { ValidationError as ValidationError5, brandAsBackend } from "@cloudbitmaps/core/driver-kit";
 import { S3Client } from "@aws-sdk/client-s3";
 
 // src/storage.ts
 import {
   NotFoundError,
-  TransientError,
-  ValidationError as ValidationError2,
+  TransientError as TransientError2,
+  ValidationError as ValidationError3,
   WriteConflictError,
   isNotFoundError,
   isValidationError,
   isWriteConflictError
 } from "@cloudbitmaps/core/driver-kit";
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import {
   AbortMultipartUploadCommand,
   CompleteMultipartUploadCommand,
@@ -100,6 +100,12 @@ function isPreconditionFailed(err) {
 function isConditionalConflict(err) {
   return isPreconditionFailed(err) || errorName(err) === "ConditionalRequestConflict" || httpStatus(err) === 409;
 }
+function isThrottle(err) {
+  return errorName(err) === "SlowDown" || httpStatus(err) === 503;
+}
+function isNoSuchUpload(err) {
+  return errorName(err) === "NoSuchUpload";
+}
 function isNotFound(err) {
   const name = errorName(err);
   return name === "NoSuchKey" || name === "NotFound" || httpStatus(err) === 404;
@@ -123,6 +129,43 @@ function totalFromContentRange(contentRange) {
   return Number.isSafeInteger(total) ? total : void 0;
 }
 
+// src/read-timeout.ts
+import { TransientError, ValidationError as ValidationError2 } from "@cloudbitmaps/core/driver-kit";
+var DEFAULT_READ_TIMEOUT_MS = 0;
+var MAX_TIMER_MS = 2147483647;
+function resolveReadTimeoutMs(value) {
+  if (value === void 0) return DEFAULT_READ_TIMEOUT_MS;
+  if (!Number.isSafeInteger(value) || value < 0 || value > MAX_TIMER_MS) {
+    throw new ValidationError2(
+      `readTimeoutMs must be a non-negative safe integer no larger than ${MAX_TIMER_MS}; got ${describe(value)}`
+    );
+  }
+  return value;
+}
+function describe(value) {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  return value === null ? "null" : typeof value;
+}
+async function timedRead(operation, timeoutMs, read) {
+  if (timeoutMs === 0) return read(void 0);
+  const controller = new AbortController();
+  let timer;
+  const timedOut = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new TransientError(`S3 ${operation} timed out after ${timeoutMs} ms`));
+      controller.abort();
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([read({ abortSignal: controller.signal }), timedOut]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // src/send-once.ts
 var NO_RETRY = {
   name: "retryMiddleware",
@@ -138,27 +181,37 @@ function sendOnce(client, command) {
 // src/storage.ts
 var S3_PART_BYTES = 8 * 1024 * 1024;
 var S3_MAX_PARTS = 1e4;
+var WRITE_ID_KEY = "cbwid";
+var THROTTLE_RESENDS = 3;
+var THROTTLE_BASE_DELAY_MS = 500;
+var REAL_TIME = {
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+};
 var S3StorageDriver = class {
   client;
   bucket;
   prefix;
   maxObjectBytes;
   partBytes;
+  readTimeoutMs;
+  clock;
   constructor(options) {
     this.client = options.client;
     this.bucket = options.bucket;
     this.prefix = normalizeObjectPrefix(options.prefix);
+    this.clock = options.clock ?? REAL_TIME;
     for (const [name, value] of [
       ["partBytes", options.partBytes],
       ["maxObjectBytes", options.maxObjectBytes]
     ]) {
       if (value !== void 0 && (!Number.isSafeInteger(value) || value < 1)) {
-        throw new ValidationError2(`${name} must be a positive safe integer; got ${value}`);
+        throw new ValidationError3(`${name} must be a positive safe integer; got ${value}`);
       }
     }
     const requestedPart = Math.max(options.partBytes ?? S3_PART_BYTES, 5 * 1024 * 1024);
     this.maxObjectBytes = options.maxObjectBytes ?? requestedPart * S3_MAX_PARTS;
     this.partBytes = Math.max(requestedPart, Math.ceil(this.maxObjectBytes / S3_MAX_PARTS));
+    this.readTimeoutMs = resolveReadTimeoutMs(options.readTimeoutMs);
   }
   capabilities() {
     return { rangeRead: true, maxObjectBytes: this.maxObjectBytes, conditionalPut: true };
@@ -170,7 +223,9 @@ var S3StorageDriver = class {
       this.bucket,
       objectKey,
       this.partBytes,
-      this.maxObjectBytes
+      this.maxObjectBytes,
+      this.readTimeoutMs,
+      this.clock
     );
     try {
       await write(sink);
@@ -190,61 +245,68 @@ var S3StorageDriver = class {
   }
   async getRange(key, offset, length) {
     if (!Number.isInteger(offset) || !Number.isInteger(length) || offset < 0 || length < 0) {
-      throw new ValidationError2(`invalid range offset=${offset} length=${length}`);
+      throw new ValidationError3(`invalid range offset=${offset} length=${length}`);
     }
     const objectKey = storageObjectKey(this.prefix, key);
     if (length === 0) return new Uint8Array(0);
-    try {
+    return this.read("GetObject", key, async (options) => {
       const res = await this.client.send(
         new GetObjectCommand({
           Bucket: this.bucket,
           Key: objectKey,
           Range: `bytes=${offset}-${offset + length - 1}`
-        })
+        }),
+        options
       );
       const bytes = await collect(res.Body);
       if (bytes.length !== length) {
-        throw new ValidationError2(
+        throw new ValidationError3(
           `range [${offset}, ${offset + length}) out of bounds (got ${bytes.length}B)`
         );
       }
       return bytes;
-    } catch (err) {
-      throw this.mapReadError(err, key);
-    }
+    });
   }
   async getTail(key, maxBytes) {
     const objectKey = storageObjectKey(this.prefix, key);
     if (maxBytes <= 0) {
-      try {
-        const head = await this.client.send(
-          new HeadObjectCommand({ Bucket: this.bucket, Key: objectKey })
-        );
-        return { bytes: new Uint8Array(0), size: head.ContentLength ?? 0 };
-      } catch (err) {
-        throw this.mapReadError(err, key);
-      }
+      return { bytes: new Uint8Array(0), size: await this.headSize(key, objectKey) ?? 0 };
     }
-    try {
+    const { bytes, contentRange } = await this.read("GetObject", key, async (options) => {
       const res = await this.client.send(
-        new GetObjectCommand({ Bucket: this.bucket, Key: objectKey, Range: `bytes=-${maxBytes}` })
+        new GetObjectCommand({ Bucket: this.bucket, Key: objectKey, Range: `bytes=-${maxBytes}` }),
+        options
       );
-      const bytes = await collect(res.Body);
-      let size = totalFromContentRange(res.ContentRange);
-      if (size === void 0) {
-        if (bytes.length === maxBytes) {
-          const head = await this.client.send(
-            new HeadObjectCommand({ Bucket: this.bucket, Key: objectKey })
-          );
-          size = head.ContentLength ?? bytes.length;
-        } else {
-          size = bytes.length;
-        }
-      }
-      return { bytes, size };
-    } catch (err) {
-      throw this.mapReadError(err, key);
+      return { bytes: await collect(res.Body), contentRange: res.ContentRange };
+    });
+    let size = totalFromContentRange(contentRange);
+    if (size === void 0) {
+      size = bytes.length === maxBytes ? await this.headSize(key, objectKey) ?? bytes.length : bytes.length;
     }
+    return { bytes, size };
+  }
+  /** The object's size from a `HeadObject`, or `undefined` when the response does not carry one. */
+  headSize(key, objectKey) {
+    return this.read("HeadObject", key, async (options) => {
+      const head = await this.client.send(
+        new HeadObjectCommand({ Bucket: this.bucket, Key: objectKey }),
+        options
+      );
+      return head.ContentLength;
+    });
+  }
+  /**
+   * One read request under the read timeout, its failures mapped to the driver vocabulary. The timeout's own
+   * `TransientError` is raised outside the mapping, so it reaches the caller as it is.
+   */
+  read(operation, key, run) {
+    return timedRead(operation, this.readTimeoutMs, async (options) => {
+      try {
+        return await run(options);
+      } catch (err) {
+        throw this.mapReadError(err, key);
+      }
+    });
   }
   async delete(key) {
     try {
@@ -288,7 +350,7 @@ var S3StorageDriver = class {
       return new NotFoundError(`no such generation: ${key.segment}.${key.generation}`);
     }
     if (isInvalidRange(err)) {
-      return new ValidationError2(`range out of bounds for ${key.segment}.${key.generation}`);
+      return new ValidationError3(`range out of bounds for ${key.segment}.${key.generation}`);
     }
     return this.mapError(err);
   }
@@ -300,7 +362,7 @@ var S3StorageDriver = class {
    */
   mapError(err) {
     if (isTransient(err)) {
-      return new TransientError(
+      return new TransientError2(
         `transient S3 fault: ${err?.name ?? "unknown"}`,
         { cause: err }
       );
@@ -318,18 +380,22 @@ function concatBytes(parts, total) {
   return out;
 }
 var S3MultipartSink = class {
-  constructor(client, bucket, objectKey, partBytes, maxObjectBytes) {
+  constructor(client, bucket, objectKey, partBytes, maxObjectBytes, readTimeoutMs, clock) {
     this.client = client;
     this.bucket = bucket;
     this.objectKey = objectKey;
     this.partBytes = partBytes;
     this.maxObjectBytes = maxObjectBytes;
+    this.readTimeoutMs = readTimeoutMs;
+    this.clock = clock;
   }
   client;
   bucket;
   objectKey;
   partBytes;
   maxObjectBytes;
+  readTimeoutMs;
+  clock;
   hash = createHash("sha256");
   pending = [];
   pendingLen = 0;
@@ -337,11 +403,13 @@ var S3MultipartSink = class {
   uploadId;
   partNumber = 0;
   parts = [];
+  /** This write's own id, stored in the object's user metadata, outside the `.crbm` bytes: see {@link commit}. */
+  writeId = randomBytes(16).toString("hex");
   async write(bytes) {
     if (bytes.length === 0) return;
     this.total += bytes.length;
     if (this.total > this.maxObjectBytes) {
-      throw new ValidationError2(`object exceeds maxObjectBytes ${this.maxObjectBytes}`);
+      throw new ValidationError3(`object exceeds maxObjectBytes ${this.maxObjectBytes}`);
     }
     this.hash.update(bytes);
     this.pending.push(bytes);
@@ -352,10 +420,15 @@ var S3MultipartSink = class {
   async flushPart() {
     if (this.uploadId === void 0) {
       const res2 = await this.client.send(
-        new CreateMultipartUploadCommand({ Bucket: this.bucket, Key: this.objectKey })
+        new CreateMultipartUploadCommand({
+          Bucket: this.bucket,
+          Key: this.objectKey,
+          Metadata: { [WRITE_ID_KEY]: this.writeId }
+          // stored on the object the completion makes
+        })
       );
       if (res2.UploadId === void 0) {
-        throw new TransientError("S3 CreateMultipartUpload returned no UploadId");
+        throw new TransientError2("S3 CreateMultipartUpload returned no UploadId");
       }
       this.uploadId = res2.UploadId;
     }
@@ -364,7 +437,7 @@ var S3MultipartSink = class {
     this.pendingLen = 0;
     this.partNumber += 1;
     if (this.partNumber > S3_MAX_PARTS) {
-      throw new ValidationError2(`multipart upload exceeded the S3 ${S3_MAX_PARTS}-part limit`);
+      throw new ValidationError3(`multipart upload exceeded the S3 ${S3_MAX_PARTS}-part limit`);
     }
     const res = await this.client.send(
       new UploadPartCommand({
@@ -381,35 +454,107 @@ var S3MultipartSink = class {
   async finish() {
     const sha256 = this.hash.digest("hex");
     if (this.uploadId === void 0) {
-      await sendOnce(
+      const body = concatBytes(this.pending, this.pendingLen);
+      await this.commit(
+        "PutObject",
+        () => sendOnce(
+          this.client,
+          new PutObjectCommand({
+            Bucket: this.bucket,
+            Key: this.objectKey,
+            Body: body,
+            IfNoneMatch: "*",
+            // write-once
+            Metadata: { [WRITE_ID_KEY]: this.writeId }
+          })
+        )
+      );
+      return { size: this.total, sha256 };
+    }
+    if (this.pendingLen > 0) await this.flushPart();
+    const uploadId = this.uploadId;
+    await this.commit(
+      "CompleteMultipartUpload",
+      () => sendOnce(
         this.client,
-        new PutObjectCommand({
+        new CompleteMultipartUploadCommand({
           Bucket: this.bucket,
           Key: this.objectKey,
-          Body: concatBytes(this.pending, this.pendingLen),
+          UploadId: uploadId,
+          MultipartUpload: { Parts: this.parts },
           IfNoneMatch: "*"
-          // write-once
+          // write-once: fail if the object already exists
         })
-      );
-      return { size: this.total, sha256 };
-    }
-    if (this.pendingLen > 0) await this.flushPart();
-    await sendOnce(
-      this.client,
-      new CompleteMultipartUploadCommand({
-        Bucket: this.bucket,
-        Key: this.objectKey,
-        UploadId: this.uploadId,
-        MultipartUpload: { Parts: this.parts },
-        IfNoneMatch: "*"
-        // write-once: fail if the object already exists
-      })
+      )
     );
     this.uploadId = void 0;
     return { size: this.total, sha256 };
   }
+  /**
+   * Send the commit (`send` sends it once, with the SDK's retry off), and again after a throttle, up to
+   * {@link THROTTLE_RESENDS} times, waiting a full-jitter backoff before each. Any other failure is thrown at once.
+   * Once the commit has been sent again, an answer that can be an earlier send that landed or is still landing (a
+   * precondition failure, a concurrent-write conflict, or an upload S3 no longer knows) is settled by reading the
+   * object back. The object is never overwritten, so the id it holds says who wrote it:
+   *
+   * - this write's own id: a success;
+   * - another's id, or none (an object an earlier release wrote): the conflict it reads as;
+   * - nothing stored: a `412` still reads as the conflict it answered (an object was there, and is gone). A `409`
+   *   and an unknown upload are an unknown outcome, since the first send may still be applying: {@link TransientError},
+   *   and never a report that nothing was written.
+   *
+   * A failed read-back throws, and is neither. Exhausted, it throws {@link TransientError}; nothing is deleted.
+   */
+  async commit(operation, send) {
+    for (let resent = 0; ; resent++) {
+      try {
+        await send();
+        return;
+      } catch (err) {
+        if (resent > 0 && (isConditionalConflict(err) || isNoSuchUpload(err))) {
+          const stored = await this.storedObject();
+          if (stored?.id === this.writeId) return;
+          if (stored === void 0 && !isPreconditionFailed(err)) {
+            throw new TransientError2(
+              `S3 ${operation}: ${this.objectKey} is not stored, and the first send may still be applying`,
+              { cause: err }
+            );
+          }
+          if (isConditionalConflict(err)) throw err;
+          throw new WriteConflictError(`generation already exists (write-once): ${this.objectKey}`);
+        }
+        if (!isThrottle(err)) throw err;
+        if (resent >= THROTTLE_RESENDS) {
+          throw new TransientError2(
+            `S3 ${operation} was throttled on each of its ${resent + 1} sends; the object may or may not exist`,
+            { cause: err }
+          );
+        }
+        await this.clock.sleep(Math.floor(Math.random() * THROTTLE_BASE_DELAY_MS * 2 ** resent));
+      }
+    }
+  }
+  /**
+   * The object stored under the key: `undefined` when none is there, otherwise the write id it carries (`id` is
+   * `undefined` for an object that carries none). A failed read throws.
+   */
+  storedObject() {
+    return timedRead("HeadObject", this.readTimeoutMs, async (options) => {
+      try {
+        const head = await this.client.send(
+          new HeadObjectCommand({ Bucket: this.bucket, Key: this.objectKey }),
+          options
+        );
+        return { id: head.Metadata?.[WRITE_ID_KEY] };
+      } catch (err) {
+        if (isNotFound(err)) return void 0;
+        throw err;
+      }
+    });
+  }
   /** Best-effort cleanup of an in-flight multipart upload after an error (a leaked MPU is reaped by a bucket
-   * lifecycle rule; never a correctness issue). No-op if nothing was started or it already completed. */
+   * lifecycle rule; never a correctness issue). No-op if nothing was started or it already completed. It aborts an
+   * upload, never an object: a completion that landed survives it. */
   async abort() {
     if (this.uploadId === void 0) return;
     const id = this.uploadId;
@@ -434,47 +579,189 @@ import {
   IntegrityError,
   MAX_ROW_BYTES,
   ObjectStoreRegistry,
-  TransientError as TransientError2,
+  TransientError as TransientError3,
+  ValidationError as ValidationError4,
   WriteConflictError as WriteConflictError2,
   normalizeObjectPrefix as normalizeObjectPrefix2
 } from "@cloudbitmaps/core/driver-kit";
 import {
+  DeleteObjectCommand as DeleteObjectCommand3,
   GetObjectCommand as GetObjectCommand2,
   ListObjectsV2Command as ListObjectsV2Command2,
-  PutObjectCommand as PutObjectCommand2
+  PutObjectCommand as PutObjectCommand3
 } from "@aws-sdk/client-s3";
-var S3Store = class {
-  constructor(client, bucket) {
+
+// src/client-probe.ts
+import { DeleteObjectCommand as DeleteObjectCommand2, PutObjectCommand as PutObjectCommand2 } from "@aws-sdk/client-s3";
+var PROBE_KEY = "cloudbitmaps-probe";
+var PLACEHOLDER_CREDENTIALS = { accessKeyId: "cloudbitmaps-probe", secretAccessKey: "unused" };
+var NEVER_SENDS = {
+  handle: () => Promise.reject(new Error("the client probe was asked to send a request")),
+  updateHttpClientConfig: () => {
+  },
+  httpHandlerConfigs: () => ({}),
+  destroy: () => {
+  }
+};
+var SILENT_LOGGER = {
+  debug: () => {
+  },
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: () => {
+  }
+};
+function cloneForProbe(client) {
+  const parts = client;
+  if (typeof parts.send !== "function" || typeof parts.config !== "object" || parts.config === null) {
+    return void 0;
+  }
+  if (typeof parts.constructor !== "function" || parts.constructor === Object) return void 0;
+  const Class = parts.constructor;
+  const clone = new Class({
+    ...parts.config,
+    credentials: PLACEHOLDER_CREDENTIALS,
+    requestHandler: NEVER_SENDS,
+    logger: SILENT_LOGGER
+  });
+  return typeof clone.send === "function" && clone.middlewareStack != null ? clone : void 0;
+}
+async function serialise(client, command) {
+  let seen;
+  command.middlewareStack.addRelativeTo(
+    () => (args) => {
+      seen = args.request;
+      return Promise.resolve({ response: {}, output: { $metadata: {} } });
+    },
+    { relation: "after", toMiddleware: "serializerMiddleware", name: "cloudbitmapsProbe" }
+  );
+  const handler = command.resolveMiddleware(client.middlewareStack, client.config, {});
+  await handler(command);
+  if (seen === void 0) throw new Error("the probe saw no request");
+  return seen;
+}
+var hasHeader = (request, name) => request.headers?.[name] !== void 0;
+async function probeClient(client, bucket) {
+  let probe;
+  try {
+    probe = cloneForProbe(client);
+    if (probe === void 0) return void 0;
+    const del = await serialise(
+      probe,
+      new DeleteObjectCommand2({ Bucket: bucket, Key: PROBE_KEY, IfMatch: '"probe"' })
+    );
+    const put = await serialise(
+      probe,
+      new PutObjectCommand2({
+        Bucket: bucket,
+        Key: PROBE_KEY,
+        Body: new Uint8Array(0),
+        IfMatch: '"probe"',
+        IfNoneMatch: "*"
+      })
+    );
+    if (typeof del.hostname !== "string" || del.hostname === "") return void 0;
+    return {
+      host: del.hostname,
+      sendsDeleteIfMatch: hasHeader(del, "if-match"),
+      sendsPutIfMatch: hasHeader(put, "if-match"),
+      sendsPutIfNoneMatch: hasHeader(put, "if-none-match")
+    };
+  } catch {
+    return void 0;
+  } finally {
+    probe?.destroy();
+  }
+}
+var AWS_DOMAINS = [".amazonaws.com", ".amazonaws.com.cn"];
+function isAwsS3Host(hostname) {
+  const host = hostname.toLowerCase().replace(/\.$/, "");
+  if (!AWS_DOMAINS.some((domain) => host.endsWith(domain))) return false;
+  return host.split(".").some((label) => label === "s3" || label.startsWith("s3-") || label.startsWith("s3express-"));
+}
+
+// src/registry.ts
+var S3RegistryStore = class {
+  constructor(client, bucket, readTimeoutMs, explicitConditionalDelete) {
     this.client = client;
     this.bucket = bucket;
+    this.readTimeoutMs = readTimeoutMs;
+    this.explicitConditionalDelete = explicitConditionalDelete;
   }
   client;
   bucket;
+  readTimeoutMs;
+  explicitConditionalDelete;
   label = "S3";
-  async read(key) {
-    let res;
-    try {
-      res = await this.client.send(new GetObjectCommand2({ Bucket: this.bucket, Key: key }));
-    } catch (err) {
-      if (isNotFound(err)) return null;
-      throw mapError(err);
-    }
-    if ((res.ContentLength ?? 0) > MAX_ROW_BYTES) {
-      throw new IntegrityError(
-        `registry object ${res.ContentLength}B exceeds cap ${MAX_ROW_BYTES}B`
+  probed;
+  facts;
+  /**
+   * Whether a delete may rely on `If-Match`: the caller's setting, else whether the client's host is AWS S3, and in
+   * neither case when the SDK is seen not to send the header. `false` until the client has been asked, unless the caller
+   * vouched for the store.
+   */
+  get conditionalDelete() {
+    if (this.explicitConditionalDelete === false) return false;
+    const facts = this.facts;
+    if (this.explicitConditionalDelete === true) return facts?.sendsDeleteIfMatch !== false;
+    return facts !== void 0 && facts.sendsDeleteIfMatch && isAwsS3Host(facts.host);
+  }
+  /** Ask the client once what it does with the registry's requests; every caller waits for the same answer. */
+  settle() {
+    this.probed ??= probeClient(this.client, this.bucket).then((facts) => {
+      this.facts = facts;
+    });
+    return this.probed;
+  }
+  /** Refuse a write the SDK would send without its precondition: it would land as a plain overwrite. */
+  refuseUnfencedWrites(expect) {
+    const header = expect === "absent" ? "If-None-Match" : "If-Match";
+    const sent = expect === "absent" ? this.facts?.sendsPutIfNoneMatch : this.facts?.sendsPutIfMatch;
+    if (sent === false) {
+      throw new ValidationError4(
+        `the S3 client does not send ${header} on a PutObject: its @aws-sdk/client-s3 predates the member, so a registry write would overwrite whatever is there and lose a concurrent writer's change. Use a newer @aws-sdk/client-s3; the registry sent nothing`
       );
     }
-    if (res.Body === void 0) {
-      throw new IntegrityError(`registry object has an empty body: ${key}`);
-    }
-    const bytes = await res.Body.transformToByteArray();
-    return { bytes, version: res.ETag ?? "" };
+  }
+  async read(key) {
+    await this.settle();
+    return timedRead("GetObject", this.readTimeoutMs, async (options) => {
+      let res;
+      try {
+        res = await this.client.send(
+          new GetObjectCommand2({ Bucket: this.bucket, Key: key }),
+          options
+        );
+      } catch (err) {
+        if (isNotFound(err)) return null;
+        throw mapError(err);
+      }
+      try {
+        if ((res.ContentLength ?? 0) > MAX_ROW_BYTES) {
+          throw new IntegrityError(
+            `registry object ${res.ContentLength}B exceeds cap ${MAX_ROW_BYTES}B`
+          );
+        }
+        if (res.Body === void 0) {
+          throw new IntegrityError(`registry object has an empty body: ${key}`);
+        }
+        const bytes = await res.Body.transformToByteArray();
+        return { bytes, version: res.ETag ?? "" };
+      } catch (err) {
+        destroyBody(res.Body);
+        throw err instanceof IntegrityError ? err : mapError(err);
+      }
+    });
   }
   async write(key, body, expect) {
+    await this.settle();
+    this.refuseUnfencedWrites(expect);
     try {
       await sendOnce(
         this.client,
-        new PutObjectCommand2({
+        new PutObjectCommand3({
           Bucket: this.bucket,
           Key: key,
           Body: body,
@@ -490,7 +777,21 @@ var S3Store = class {
       throw mapError(err);
     }
   }
+  async delete(key, expect) {
+    try {
+      await sendOnce(
+        this.client,
+        new DeleteObjectCommand3({ Bucket: this.bucket, Key: key, IfMatch: expect.version })
+      );
+    } catch (err) {
+      if (isConditionalConflict(err) || isNotFound(err)) {
+        throw new WriteConflictError2(`registry OCC conflict deleting ${key}`);
+      }
+      throw mapError(err);
+    }
+  }
   async *listKeys(prefix) {
+    await this.settle();
     let token;
     do {
       let res;
@@ -512,19 +813,34 @@ var S3Store = class {
     } while (token !== void 0);
   }
 };
+function destroyBody(body) {
+  body?.destroy?.();
+}
 function mapError(err) {
   if (isTransient(err)) {
-    return new TransientError2(
+    return new TransientError3(
       `transient S3 fault: ${err?.name ?? "unknown"}`,
       { cause: err }
     );
   }
   return err;
 }
+function checkConditionalDelete(value) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "boolean") {
+    throw new ValidationError4(`conditionalDelete must be a boolean; got ${String(value)}`);
+  }
+  return value;
+}
 var S3RegistryDriver = class extends ObjectStoreRegistry {
   constructor(options) {
     super(
-      new S3Store(options.client, options.bucket),
+      new S3RegistryStore(
+        options.client,
+        options.bucket,
+        resolveReadTimeoutMs(options.readTimeoutMs),
+        checkConditionalDelete(options.conditionalDelete)
+      ),
       normalizeObjectPrefix2(options.prefix),
       options.now ?? (() => Date.now())
     );
@@ -542,19 +858,21 @@ var S3_STORAGE_OPTION_KEYS = [
   "credentials",
   "maxObjectBytes",
   "partBytes",
-  "now"
+  "readTimeoutMs",
+  "now",
+  "conditionalDelete"
 ];
 var CLIENT_SETTINGS = ["region", "endpoint", "pathStyle", "credentials"];
 function refuseUnknown(name, options, keys, hint) {
   if (options === null || typeof options !== "object") {
-    throw new ValidationError3(
+    throw new ValidationError5(
       `${name} needs an options object \u2014 got ${options === null ? "null" : typeof options}`
     );
   }
   const unknown = Object.keys(options).filter((k) => !keys.includes(k));
   if (unknown.length > 0) {
     const list = (ks) => ks.map((k) => `\`${k}\``).join(", ");
-    throw new ValidationError3(
+    throw new ValidationError5(
       `${name} does not take ${list(unknown)}. It takes ${list(keys)}; ${hint}.`
     );
   }
@@ -569,7 +887,7 @@ var S3Storage = class {
     if (options.client !== void 0 && options.client !== null) {
       const ignored = CLIENT_SETTINGS.filter((k) => options[k] !== void 0);
       if (ignored.length > 0) {
-        throw new ValidationError3(
+        throw new ValidationError5(
           `S3Storage takes \`client\` OR ${CLIENT_SETTINGS.map((k) => `\`${k}\``).join(" / ")}, not both \u2014 got \`client\` with ${ignored.map((k) => `\`${k}\``).join(", ")}; the \`client\` already carries them, so configure them on the client, or drop \`client\``
         );
       }
@@ -585,7 +903,8 @@ var S3Storage = class {
     const shared = {
       client: this.client,
       bucket: options.bucket,
-      ...options.prefix === void 0 ? {} : { prefix: options.prefix }
+      ...options.prefix === void 0 ? {} : { prefix: options.prefix },
+      ...options.readTimeoutMs === void 0 ? {} : { readTimeoutMs: options.readTimeoutMs }
     };
     this.storage = new S3StorageDriver({
       ...shared,
@@ -594,7 +913,8 @@ var S3Storage = class {
     });
     this.registry = new S3RegistryDriver({
       ...shared,
-      ...options.now === void 0 ? {} : { now: options.now }
+      ...options.now === void 0 ? {} : { now: options.now },
+      ...options.conditionalDelete === void 0 ? {} : { conditionalDelete: options.conditionalDelete }
     });
     brandAsBackend(this);
   }