@cloudbitmaps/s3 0.19.1 → 0.21.0

package/dist/index.js

@@ -1,7 +1,17 @@
 // src/backend.ts
-import { ValidationError as ValidationError5, brandAsBackend } from "@cloudbitmaps/core/driver-kit";
+import {
+  ValidationError as ValidationError5,
+  brandAsBackend,
+  refuseUnknownOptions,
+  requirePositiveInt as requirePositiveInt2
+} from "@cloudbitmaps/core/driver-kit";
 import { S3Client } from "@aws-sdk/client-s3";
 
+// src/defined.ts
+function defined(values) {
+  return Object.fromEntries(Object.entries(values).filter(([, v]) => v !== void 0));
+}
+
 // src/storage.ts
 import {
   IntegrityError,
@@ -9,61 +19,42 @@ import {
   TransientError as TransientError2,
   ValidationError as ValidationError3,
   WriteConflictError,
+  concatBytes,
   isNotFoundError,
   isValidationError,
-  isWriteConflictError
+  isWriteConflictError,
+  normalizeObjectPrefix,
+  parseGenerationFromKey,
+  requireBool,
+  requirePositiveInt,
+  segmentObjectPrefix,
+  storageObjectKey,
+  toTransient
 } from "@cloudbitmaps/core/driver-kit";
 import { createHash, randomBytes } from "node:crypto";
 import {
   AbortMultipartUploadCommand,
   CompleteMultipartUploadCommand,
   CreateMultipartUploadCommand,
-  DeleteObjectCommand,
+  DeleteObjectCommand as DeleteObjectCommand2,
   GetObjectCommand,
   HeadObjectCommand,
   ListObjectsV2Command,
-  PutObjectCommand,
+  PutObjectCommand as PutObjectCommand2,
   UploadPartCommand
 } from "@aws-sdk/client-s3";
 
-// src/keys.ts
-import {
-  ValidationError,
-  encodeNameForKey,
-  namespaceKeyPart,
-  prefixPart,
-  validateSegmentRef
-} from "@cloudbitmaps/core/driver-kit";
-import { normalizeObjectPrefix } from "@cloudbitmaps/core/driver-kit";
-var SUFFIX = ".crbm";
-function segmentObjectPrefix(prefix, ref) {
-  validateSegmentRef(ref);
-  return `${prefixPart(prefix)}${namespaceKeyPart(ref.namespace)}/segments/${encodeNameForKey(ref.segment)}.`;
-}
-function storageObjectKey(prefix, key) {
-  if (!Number.isInteger(key.generation) || key.generation < 0) {
-    throw new ValidationError(`generation must be a non-negative integer; got ${key.generation}`);
-  }
-  return `${segmentObjectPrefix(prefix, key)}${key.generation}${SUFFIX}`;
-}
-function parseGenerationFromKey(segmentPrefix, objectKey) {
-  if (!objectKey.startsWith(segmentPrefix) || !objectKey.endsWith(SUFFIX)) return null;
-  const middle = objectKey.slice(segmentPrefix.length, objectKey.length - SUFFIX.length);
-  if (!/^(0|[1-9]\d*)$/.test(middle)) return null;
-  const generation = Number(middle);
-  return Number.isSafeInteger(generation) ? generation : null;
-}
+// src/s3-errors.ts
+import { ValidationError } from "@cloudbitmaps/core/driver-kit";
 
 // src/aws-errors.ts
+import { isTransportFault } from "@cloudbitmaps/core/driver-kit";
 function httpStatus(err) {
   return err?.$metadata?.httpStatusCode;
 }
 function errorName(err) {
   return err?.name;
 }
-function errorCode(err) {
-  return err?.code;
-}
 function isSdkRetryable(err) {
   return err?.$retryable != null;
 }
@@ -78,19 +69,10 @@ var NETWORK_NAMES = /* @__PURE__ */ new Set([
   "NetworkingError",
   "AbortError"
 ]);
-var NETWORK_CODES = /* @__PURE__ */ new Set([
-  "ETIMEDOUT",
-  "ECONNRESET",
-  "ECONNREFUSED",
-  "EPIPE",
-  "ENOTFOUND",
-  "EAI_AGAIN",
-  "ECONNABORTED"
-]);
 var NETWORK_MESSAGE = /socket hang up|network (error|failure)|(connection|request|socket|operation|read|write)\s+tim(e|ed)\s?out|connection (reset|refused|aborted|closed)/i;
 function isNetworkOrTimeout(err) {
   if (NETWORK_NAMES.has(errorName(err) ?? "")) return true;
-  if (NETWORK_CODES.has(errorCode(err) ?? "")) return true;
+  if (isTransportFault(err)) return true;
   return NETWORK_MESSAGE.test(err?.message ?? "");
 }
 
@@ -110,6 +92,15 @@ function isNoSuchUpload(err) {
 function isMissingBucket(err) {
   return errorName(err) === "NoSuchBucket";
 }
+function asMissingBucket(err, bucket) {
+  if (!isMissingBucket(err)) return err;
+  return Object.assign(
+    new ValidationError(
+      `the S3 bucket does not exist: ${bucket}; check the bucket name, and the region and endpoint of the client`
+    ),
+    { cause: err }
+  );
+}
 function isNotFound(err) {
   if (isMissingBucket(err)) return false;
   const name = errorName(err);
@@ -126,6 +117,9 @@ function isTransient(err) {
   if (isConditionalConflict(err) || isNotFound(err) || isInvalidRange(err)) return false;
   return errorName(err) === "SlowDown" || isServerSide(err) || isNetworkOrTimeout(err) || isSdkRetryable(err) || isClockSkewCorrected(err);
 }
+function transientFaultMessage(err) {
+  return `transient S3 fault: ${errorName(err) ?? "unknown"}`;
+}
 function spanFromContentRange(contentRange) {
   if (contentRange === void 0) return void 0;
   const match = /^\s*bytes\s+(\d+)-(\d+)\//.exec(contentRange);
@@ -313,6 +307,128 @@ function scrubCredentials(err) {
   return safe;
 }
 
+// src/client-probe.ts
+import { DeleteObjectCommand, PutObjectCommand } 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 DeleteObjectCommand({ Bucket: bucket, Key: PROBE_KEY, IfMatch: '"probe"' })
+    );
+    const put = await serialise(
+      probe,
+      new PutObjectCommand({
+        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();
+  }
+}
+function appliesDeleteIfMatch(explicit, facts) {
+  if (explicit === false) return false;
+  if (explicit === true) return facts?.sendsDeleteIfMatch !== false;
+  return facts !== void 0 && facts.sendsDeleteIfMatch && isAwsS3Host(facts.host);
+}
+var AWS_DOMAINS = [".amazonaws.com", ".amazonaws.com.cn"];
+var S3_LABELS = /* @__PURE__ */ new Set([
+  "s3",
+  "s3-fips",
+  "s3-accesspoint",
+  "s3-accesspoint-fips",
+  "s3-global",
+  "s3-object-lambda",
+  "s3-outposts",
+  "s3-external-1"
+]);
+var S3_DASH_REGION_LABEL = /^s3-(fips-)?[a-z]{2}(-gov)?-[a-z]+-\d$/;
+var S3_EXPRESS_LABEL = /^s3express-[a-z0-9-]+$/;
+var REGION_LABEL = /^[a-z]{2}(-[a-z]+)+-\d+$/;
+var isS3Label = (label) => S3_LABELS.has(label) || S3_DASH_REGION_LABEL.test(label) || S3_EXPRESS_LABEL.test(label);
+function isAwsS3Host(hostname) {
+  const host = hostname.toLowerCase().replace(/\.$/, "");
+  const domain = AWS_DOMAINS.find((d) => host.endsWith(d));
+  if (domain === void 0) return false;
+  const labels = host.slice(0, -domain.length).split(".");
+  let at = -1;
+  labels.forEach((label, i) => {
+    if (isS3Label(label)) at = i;
+  });
+  if (at === -1) return false;
+  const rest = labels.slice(at + 1);
+  let k = 0;
+  if (rest[k] === "dualstack") k++;
+  if (k < rest.length && REGION_LABEL.test(rest[k])) k++;
+  if (rest[k] === "vpce") k++;
+  return k === rest.length;
+}
+
 // src/storage.ts
 var S3_PART_BYTES = 8 * 1024 * 1024;
 var S3_MAX_PARTS = 1e4;
@@ -324,6 +440,7 @@ var THROTTLE_BASE_DELAY_MS = 500;
 var REAL_TIME = {
   sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 };
+var REAL_RNG = { next: () => Math.random() };
 var S3StorageDriver = class {
   client;
   bucket;
@@ -332,21 +449,21 @@ var S3StorageDriver = class {
   partBytes;
   readTimeoutMs;
   clock;
+  rng;
   sockets;
+  explicitConditionalDelete;
+  probed;
+  facts;
   constructor(options) {
     this.client = options.client;
+    this.explicitConditionalDelete = requireBool("conditionalDelete", options.conditionalDelete);
     this.sockets = options.sockets;
     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 ValidationError3(`${name} must be a positive safe integer; got ${value}`);
-      }
-    }
+    this.rng = options.rng ?? REAL_RNG;
+    requirePositiveInt("partBytes", options.partBytes);
+    requirePositiveInt("maxObjectBytes", options.maxObjectBytes);
     if (options.maxObjectBytes !== void 0 && options.maxObjectBytes > S3_MAX_OBJECT_BYTES) {
       throw new ValidationError3(
         `maxObjectBytes must be at most S3's 5 TiB object limit (${S3_MAX_OBJECT_BYTES}); got ${options.maxObjectBytes}`
@@ -363,7 +480,19 @@ var S3StorageDriver = class {
     this.readTimeoutMs = resolveReadTimeoutMs(options.readTimeoutMs);
   }
   capabilities() {
-    return { rangeRead: true, maxObjectBytes: this.maxObjectBytes, conditionalPut: true };
+    return {
+      rangeRead: true,
+      maxObjectBytes: this.maxObjectBytes,
+      conditionalPut: true,
+      conditionalDelete: appliesDeleteIfMatch(this.explicitConditionalDelete, this.facts)
+    };
+  }
+  /** Ask the client once where its requests go and whether it sends `If-Match` on a delete; it sends nothing. */
+  settle() {
+    this.probed ??= probeClient(this.client, this.bucket).then((facts) => {
+      this.facts = facts;
+    });
+    return this.probed;
   }
   async putImmutable(key, write) {
     const objectKey = storageObjectKey(this.prefix, key);
@@ -374,7 +503,8 @@ var S3StorageDriver = class {
       this.partBytes,
       this.maxObjectBytes,
       this.readTimeoutMs,
-      this.clock
+      this.clock,
+      this.rng
     );
     try {
       await write(sink);
@@ -432,8 +562,12 @@ var S3StorageDriver = class {
   }
   async getTail(key, maxBytes) {
     const objectKey = storageObjectKey(this.prefix, key);
+    if (!Number.isSafeInteger(maxBytes)) {
+      throw new ValidationError3(`invalid tail length ${String(maxBytes)}`);
+    }
     if (maxBytes <= 0) {
-      return { bytes: new Uint8Array(0), size: await this.headSize(key, objectKey) ?? 0 };
+      const head = await this.head(key, objectKey);
+      return withVersion({ bytes: new Uint8Array(0), size: head.size ?? 0 }, head.version);
     }
     const read = await this.read("GetObject", key, async (options) => {
       try {
@@ -451,17 +585,18 @@ var S3StorageDriver = class {
           () => this.badRead(key, "tail", `the response is longer than the ${maxBytes}B requested`),
           res.ContentLength
         );
-        return { bytes: bytes2, contentRange: res.ContentRange };
+        return { bytes: bytes2, contentRange: res.ContentRange, version: res.ETag };
       } catch (err) {
         if (isInvalidRange(err)) return { refused: err };
         throw err;
       }
     });
     if ("refused" in read) {
-      if (await this.headSize(key, objectKey) !== 0) throw this.mapReadError(read.refused, key);
-      return { bytes: new Uint8Array(0), size: 0 };
+      const head = await this.head(key, objectKey);
+      if (head.size !== 0) throw this.mapReadError(read.refused, key);
+      return withVersion({ bytes: new Uint8Array(0), size: 0 }, head.version);
     }
-    const { bytes, contentRange } = read;
+    const { bytes, contentRange, version } = read;
     let size = totalFromContentRange(contentRange);
     if (contentRange !== void 0 && !(size === 0 && bytes.length === 0)) {
       const span = spanFromContentRange(contentRange);
@@ -475,23 +610,26 @@ var S3StorageDriver = class {
       }
     }
     if (size === void 0) {
-      size = bytes.length === maxBytes ? await this.headSize(key, objectKey) ?? bytes.length : bytes.length;
+      size = bytes.length === maxBytes ? (await this.head(key, objectKey)).size ?? bytes.length : bytes.length;
     }
-    return { bytes, size };
+    return withVersion({ bytes, size }, version);
   }
   badRead(key, what, why) {
     return new ValidationError3(
       `S3 ${what} read of ${key.segment}.${key.generation} refused: ${why}`
     );
   }
-  /** The object's size from a `HeadObject`, or `undefined` when the response does not carry one. */
-  headSize(key, objectKey) {
+  /**
+   * The object's size and ETag from a `HeadObject`, each `undefined` when the response does not carry it. A missing
+   * object throws {@link NotFoundError}.
+   */
+  head(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;
+      return { size: head.ContentLength, version: head.ETag };
     });
   }
   /**
@@ -509,15 +647,43 @@ var S3StorageDriver = class {
       }
     });
   }
-  async delete(key) {
+  async delete(key, options) {
+    const objectKey = storageObjectKey(this.prefix, key);
+    const ifVersion = options?.ifVersion;
+    if (ifVersion !== void 0 && this.explicitConditionalDelete !== false) await this.settle();
+    const conditional = ifVersion !== void 0 && appliesDeleteIfMatch(this.explicitConditionalDelete, this.facts);
     try {
       await this.client.send(
-        new DeleteObjectCommand({ Bucket: this.bucket, Key: storageObjectKey(this.prefix, key) })
+        new DeleteObjectCommand2({
+          Bucket: this.bucket,
+          Key: objectKey,
+          ...conditional ? { IfMatch: ifVersion } : {}
+        })
       );
-    } catch (err) {
+    } catch (raw) {
+      const err = scrubCredentials(raw);
+      if (conditional) {
+        if (isNotFound(err)) return;
+        if (isConditionalConflict(err)) {
+          if (!await this.exists(key, objectKey)) return;
+          throw new WriteConflictError(
+            `generation ${key.segment}.${key.generation} is another object than the version given; not deleted`
+          );
+        }
+      }
       throw this.mapError(err);
     }
   }
+  /** Whether an object is under the key, from one `HeadObject`. A read that fails in any other way throws. */
+  async exists(key, objectKey) {
+    try {
+      await this.head(key, objectKey);
+      return true;
+    } catch (err) {
+      if (isNotFoundError(err)) return false;
+      throw err;
+    }
+  }
   async *list(ref) {
     const prefix = segmentObjectPrefix(this.prefix, ref);
     let token;
@@ -563,33 +729,21 @@ var S3StorageDriver = class {
     return this.mapError(err);
   }
   /**
-   * Reclassify a transient S3 fault (throttle/5xx/dropped connection) as a retryable {@link TransientError},
-   * so the store's read retry can ride it out and a write's caller can tell it from a deterministic failure;
-   * everything else propagates unchanged. The final fallback at every `client.send` site, so callers and the
-   * read retry only ever see typed errors.
+   * Reclassify a transient S3 fault (throttle/5xx/dropped connection) as a retryable {@link TransientError}, so the
+   * store's read retry can ride it out and a write's caller can tell it from a deterministic failure, and a missing
+   * bucket as a `ValidationError` that names it; everything else propagates unchanged. The final fallback at every
+   * `client.send` site, so callers and the read retry only ever see typed errors.
    */
   mapError(err) {
-    err = scrubCredentials(err);
-    if (isTransient(err)) {
-      return new TransientError2(
-        `transient S3 fault: ${err?.name ?? "unknown"}`,
-        { cause: err }
-      );
-    }
-    return err;
+    const scrubbed = asMissingBucket(scrubCredentials(err), this.bucket);
+    return toTransient(scrubbed, isTransient, transientFaultMessage);
   }
 };
-function concatBytes(parts, total) {
-  const out = new Uint8Array(total);
-  let offset = 0;
-  for (const p of parts) {
-    out.set(p, offset);
-    offset += p.length;
-  }
-  return out;
+function withVersion(tail, version) {
+  return version === void 0 ? tail : { ...tail, version };
 }
 var S3MultipartSink = class {
-  constructor(client, bucket, objectKey, partBytes, maxObjectBytes, readTimeoutMs, clock) {
+  constructor(client, bucket, objectKey, partBytes, maxObjectBytes, readTimeoutMs, clock, rng) {
     this.client = client;
     this.bucket = bucket;
     this.objectKey = objectKey;
@@ -597,6 +751,7 @@ var S3MultipartSink = class {
     this.maxObjectBytes = maxObjectBytes;
     this.readTimeoutMs = readTimeoutMs;
     this.clock = clock;
+    this.rng = rng;
   }
   client;
   bucket;
@@ -605,6 +760,7 @@ var S3MultipartSink = class {
   maxObjectBytes;
   readTimeoutMs;
   clock;
+  rng;
   hash = createHash("sha256");
   pending = [];
   pendingLen = 0;
@@ -641,7 +797,7 @@ var S3MultipartSink = class {
       }
       this.uploadId = res2.UploadId;
     }
-    const body = concatBytes(this.pending, this.pendingLen);
+    const body = concatBytes(this.pending);
     this.pending.length = 0;
     this.pendingLen = 0;
     this.partNumber += 1;
@@ -663,12 +819,12 @@ var S3MultipartSink = class {
   async finish() {
     const sha256 = this.hash.digest("hex");
     if (this.uploadId === void 0) {
-      const body = concatBytes(this.pending, this.pendingLen);
+      const body = concatBytes(this.pending);
       await this.commit(
         "PutObject",
         () => sendOnce(
           this.client,
-          new PutObjectCommand({
+          new PutObjectCommand2({
             Bucket: this.bucket,
             Key: this.objectKey,
             Body: body,
@@ -740,7 +896,7 @@ var S3MultipartSink = class {
             { cause: err }
           );
         }
-        await this.clock.sleep(Math.floor(Math.random() * THROTTLE_BASE_DELAY_MS * 2 ** resent));
+        await this.clock.sleep(Math.floor(this.rng.next() * THROTTLE_BASE_DELAY_MS * 2 ** resent));
       }
     }
   }
@@ -784,10 +940,11 @@ import {
   isIntegrityError,
   MAX_ROW_BYTES,
   ObjectStoreRegistry,
-  TransientError as TransientError3,
   ValidationError as ValidationError4,
   WriteConflictError as WriteConflictError2,
-  normalizeObjectPrefix as normalizeObjectPrefix2
+  normalizeObjectPrefix as normalizeObjectPrefix2,
+  requireBool as requireBool2,
+  toTransient as toTransient2
 } from "@cloudbitmaps/core/driver-kit";
 import {
   DeleteObjectCommand as DeleteObjectCommand3,
@@ -795,125 +952,6 @@ import {
   ListObjectsV2Command as ListObjectsV2Command2,
   PutObjectCommand as PutObjectCommand3
 } from "@aws-sdk/client-s3";
-
-// 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"];
-var S3_LABELS = /* @__PURE__ */ new Set([
-  "s3",
-  "s3-fips",
-  "s3-accesspoint",
-  "s3-accesspoint-fips",
-  "s3-global",
-  "s3-object-lambda",
-  "s3-outposts",
-  "s3-external-1"
-]);
-var S3_DASH_REGION_LABEL = /^s3-(fips-)?[a-z]{2}(-gov)?-[a-z]+-\d$/;
-var S3_EXPRESS_LABEL = /^s3express-[a-z0-9-]+$/;
-var REGION_LABEL = /^[a-z]{2}(-[a-z]+)+-\d+$/;
-var isS3Label = (label) => S3_LABELS.has(label) || S3_DASH_REGION_LABEL.test(label) || S3_EXPRESS_LABEL.test(label);
-function isAwsS3Host(hostname) {
-  const host = hostname.toLowerCase().replace(/\.$/, "");
-  const domain = AWS_DOMAINS.find((d) => host.endsWith(d));
-  if (domain === void 0) return false;
-  const labels = host.slice(0, -domain.length).split(".");
-  let at = -1;
-  labels.forEach((label, i) => {
-    if (isS3Label(label)) at = i;
-  });
-  if (at === -1) return false;
-  const rest = labels.slice(at + 1);
-  let k = 0;
-  if (rest[k] === "dualstack") k++;
-  if (k < rest.length && REGION_LABEL.test(rest[k])) k++;
-  if (rest[k] === "vpce") k++;
-  return k === rest.length;
-}
-
-// src/registry.ts
 var S3RegistryStore = class {
   constructor(client, bucket, readTimeoutMs, explicitConditionalDelete) {
     this.client = client;
@@ -934,10 +972,7 @@ var S3RegistryStore = class {
    * 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);
+    return appliesDeleteIfMatch(this.explicitConditionalDelete, this.facts);
   }
   /** Ask the client once what it does with the registry's requests; every caller waits for the same answer. */
   settle() {
@@ -967,7 +1002,7 @@ var S3RegistryStore = class {
         );
       } catch (err) {
         if (isNotFound(err)) return null;
-        throw mapError(err);
+        throw mapError(err, this.bucket);
       }
       try {
         if ((res.ContentLength ?? 0) > MAX_ROW_BYTES) {
@@ -986,7 +1021,7 @@ var S3RegistryStore = class {
         return { bytes, version: res.ETag ?? "" };
       } catch (err) {
         destroyBody(res.Body);
-        throw isIntegrityError(err) ? err : mapError(err);
+        throw isIntegrityError(err) ? err : mapError(err, this.bucket);
       }
     });
   }
@@ -1009,7 +1044,7 @@ var S3RegistryStore = class {
       if (isConditionalConflict(err)) {
         throw new WriteConflictError2(`registry OCC conflict for ${key}`);
       }
-      throw mapError(err);
+      throw mapError(err, this.bucket);
     }
   }
   async delete(key, expect) {
@@ -1022,7 +1057,7 @@ var S3RegistryStore = class {
       if (isConditionalConflict(err) || isNotFound(err)) {
         throw new WriteConflictError2(`registry OCC conflict deleting ${key}`);
       }
-      throw mapError(err);
+      throw mapError(err, this.bucket);
     }
   }
   async *listKeys(prefix) {
@@ -1039,7 +1074,7 @@ var S3RegistryStore = class {
           })
         );
       } catch (err) {
-        throw mapError(err);
+        throw mapError(err, this.bucket);
       }
       for (const obj of res.Contents ?? []) {
         if (obj.Key !== void 0) yield obj.Key;
@@ -1054,22 +1089,12 @@ var S3RegistryStore = class {
     } while (token !== void 0);
   }
 };
-function mapError(err) {
-  err = scrubCredentials(err);
-  if (isTransient(err)) {
-    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;
+function mapError(err, bucket) {
+  return toTransient2(
+    asMissingBucket(scrubCredentials(err), bucket),
+    isTransient,
+    transientFaultMessage
+  );
 }
 var S3RegistryDriver = class extends ObjectStoreRegistry {
   constructor(options) {
@@ -1078,7 +1103,7 @@ var S3RegistryDriver = class extends ObjectStoreRegistry {
         options.client,
         options.bucket,
         resolveReadTimeoutMs(options.readTimeoutMs),
-        checkConditionalDelete(options.conditionalDelete)
+        requireBool2("conditionalDelete", options.conditionalDelete)
       ),
       normalizeObjectPrefix2(options.prefix),
       options.now ?? (() => Date.now())
@@ -1216,20 +1241,6 @@ function limitSockets(client, maxSockets) {
     return handle(request, options);
   };
 }
-function refuseUnknown(name, options, keys, hint) {
-  if (options === null || typeof options !== "object") {
-    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 ValidationError5(
-      `${name} does not take ${list(unknown)}. It takes ${list(keys)}; ${hint}.`
-    );
-  }
-}
 var S3Storage = class {
   storage;
   registry;
@@ -1237,7 +1248,12 @@ var S3Storage = class {
   client;
   sockets;
   constructor(options) {
-    refuseUnknown("S3Storage", options, S3_STORAGE_OPTION_KEYS, "an S3 client goes in `client`");
+    refuseUnknownOptions(
+      "S3Storage",
+      options,
+      S3_STORAGE_OPTION_KEYS,
+      "an S3 client goes in `client`"
+    );
     if (typeof options.bucket !== "string" || options.bucket.length === 0) {
       throw new ValidationError5("S3Storage needs a `bucket`: the name of one, a non-empty string");
     }
@@ -1255,37 +1271,35 @@ var S3Storage = class {
       }
       this.client = options.client;
     } else {
-      const { maxSockets = DEFAULT_MAX_SOCKETS } = options;
-      if (!Number.isSafeInteger(maxSockets) || maxSockets < 1) {
-        throw new ValidationError5(
-          `maxSockets must be a positive safe integer; got ${describe(options.maxSockets)}`
-        );
-      }
-      this.client = new S3Client({
-        ...options.region === void 0 ? {} : { region: options.region },
-        ...options.endpoint === void 0 ? {} : { endpoint: options.endpoint },
-        ...options.pathStyle === void 0 ? {} : { forcePathStyle: options.pathStyle },
-        ...options.credentials === void 0 ? {} : { credentials: options.credentials }
-      });
+      const maxSockets = requirePositiveInt2("maxSockets", options.maxSockets) ?? DEFAULT_MAX_SOCKETS;
+      this.client = new S3Client(
+        defined({
+          credentials: options.credentials,
+          region: options.region,
+          endpoint: options.endpoint,
+          forcePathStyle: options.pathStyle
+        })
+      );
       limitSockets(this.client, maxSockets);
     }
     this.sockets = new SocketAdvisory(this.client, options.bucket);
     const shared = {
       client: this.client,
       bucket: options.bucket,
-      ...options.prefix === void 0 ? {} : { prefix: options.prefix },
-      ...options.readTimeoutMs === void 0 ? {} : { readTimeoutMs: options.readTimeoutMs }
+      ...defined({ prefix: options.prefix, readTimeoutMs: options.readTimeoutMs })
     };
     this.storage = new S3StorageDriver({
       ...shared,
       sockets: this.sockets,
-      ...options.maxObjectBytes === void 0 ? {} : { maxObjectBytes: options.maxObjectBytes },
-      ...options.partBytes === void 0 ? {} : { partBytes: options.partBytes }
+      ...defined({
+        maxObjectBytes: options.maxObjectBytes,
+        partBytes: options.partBytes,
+        conditionalDelete: options.conditionalDelete
+      })
     });
     this.registry = new S3RegistryDriver({
       ...shared,
-      ...options.now === void 0 ? {} : { now: options.now },
-      ...options.conditionalDelete === void 0 ? {} : { conditionalDelete: options.conditionalDelete }
+      ...defined({ now: options.now, conditionalDelete: options.conditionalDelete })
     });
     brandAsBackend(this);
   }