@cloudbitmaps/s3 0.22.0 → 0.23.0

package/dist/index.js

@@ -2,7 +2,11 @@
 import {
   ValidationError as ValidationError5,
   brandAsBackend,
+  normalizeObjectPrefix as normalizeObjectPrefix3,
+  prefixPart,
   refuseUnknownOptions,
+  requireBool as requireBool3,
+  requireNonEmptyString,
   requirePositiveInt as requirePositiveInt2
 } from "@cloudbitmaps/core/driver-kit";
 import { S3Client } from "@aws-sdk/client-s3";
@@ -12,38 +16,9 @@ function defined(values) {
   return Object.fromEntries(Object.entries(values).filter(([, v]) => v !== void 0));
 }
 
-// src/storage.ts
-import {
-  errorKind,
-  IntegrityError,
-  NotFoundError as NotFoundError2,
-  TransientError as TransientError2,
-  ValidationError as ValidationError3,
-  WriteConflictError,
-  concatBytes,
-  normalizeObjectPrefix,
-  parseGenerationFromKey,
-  requireBool,
-  requirePositiveInt,
-  segmentObjectPrefix,
-  storageObjectKey,
-  toTransient
-} from "@cloudbitmaps/core/driver-kit";
-import { createHash, randomBytes } from "node:crypto";
-import {
-  AbortMultipartUploadCommand,
-  CompleteMultipartUploadCommand,
-  CreateMultipartUploadCommand,
-  DeleteObjectCommand as DeleteObjectCommand2,
-  GetObjectCommand,
-  HeadObjectCommand,
-  ListObjectsV2Command,
-  PutObjectCommand as PutObjectCommand2,
-  UploadPartCommand
-} from "@aws-sdk/client-s3";
-
-// src/s3-errors.ts
-import { ValidationError } from "@cloudbitmaps/core/driver-kit";
+// src/lifecycle.ts
+import { GetBucketLifecycleConfigurationCommand } from "@aws-sdk/client-s3";
+import { TransientError as TransientError2 } from "@cloudbitmaps/core/driver-kit";
 
 // src/aws-errors.ts
 import { isTransportFault } from "@cloudbitmaps/core/driver-kit";
@@ -74,74 +49,14 @@ function isNetworkOrTimeout(err) {
   return NETWORK_MESSAGE.test(err?.message ?? "");
 }
 
-// src/s3-errors.ts
-function isPreconditionFailed(err) {
-  return errorName(err) === "PreconditionFailed" || httpStatus(err) === 412;
-}
-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 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);
-  return name === "NoSuchKey" || name === "NotFound" || httpStatus(err) === 404;
-}
-function isInvalidRange(err) {
-  return errorName(err) === "InvalidRange" || httpStatus(err) === 416;
-}
-function isClockSkewCorrected(err) {
-  const e = err;
-  return e?.$metadata?.clockSkewCorrected === true;
-}
-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);
-  if (match === null) return void 0;
-  const start = Number(match[1]);
-  const end = Number(match[2]);
-  return Number.isSafeInteger(start) && Number.isSafeInteger(end) ? { start, end } : void 0;
-}
-function totalFromContentRange(contentRange) {
-  if (contentRange === void 0) return void 0;
-  const match = /\/(\d+)\s*$/.exec(contentRange);
-  if (match === null) return void 0;
-  const total = Number(match[1]);
-  return Number.isSafeInteger(total) ? total : void 0;
-}
-
 // src/read-timeout.ts
-import { TransientError, ValidationError as ValidationError2 } from "@cloudbitmaps/core/driver-kit";
+import { TransientError, ValidationError } 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(
+    throw new ValidationError(
       `readTimeoutMs must be a non-negative safe integer no larger than ${MAX_TIMER_MS}; got ${describe(value)}`
     );
   }
@@ -171,57 +86,6 @@ async function timedRead(operation, timeoutMs, read) {
   }
 }
 
-// src/send-once.ts
-var NO_RETRY = {
-  name: "retryMiddleware",
-  step: "finalizeRequest",
-  priority: "high",
-  override: true
-};
-function sendOnce(client, command) {
-  command.middlewareStack.add((next) => next, NO_RETRY);
-  return client.send(command, {});
-}
-
-// src/bounded-body.ts
-import { NotFoundError } from "@cloudbitmaps/core/driver-kit";
-function destroyBody(body) {
-  body?.destroy?.();
-}
-async function readBounded(body, maxBytes, oversize, advertised) {
-  if (body === void 0) throw new NotFoundError("S3 GetObject returned an empty body");
-  if (advertised !== void 0 && advertised > maxBytes) {
-    destroyBody(body);
-    throw oversize();
-  }
-  if (typeof body[Symbol.asyncIterator] !== "function") {
-    const bytes = await body.transformToByteArray();
-    if (bytes.length > maxBytes) throw oversize();
-    return bytes;
-  }
-  const chunks = [];
-  let total = 0;
-  let done = false;
-  try {
-    for await (const chunk of body) {
-      const piece = typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk;
-      total += piece.length;
-      if (total > maxBytes) throw oversize();
-      chunks.push(piece);
-    }
-    done = true;
-  } finally {
-    if (!done) destroyBody(body);
-  }
-  const out = new Uint8Array(total);
-  let at = 0;
-  for (const piece of chunks) {
-    out.set(piece, at);
-    at += piece.length;
-  }
-  return out;
-}
-
 // src/scrub-error.ts
 import { types } from "node:util";
 var TRANSPORT = /* @__PURE__ */ new Set([
@@ -439,6 +303,279 @@ function scrubCredentials(err) {
   return ctx.changed && copy !== OMIT ? copy : err;
 }
 
+// src/lifecycle.ts
+var MAX_MESSAGE = 200;
+var MAX_FIELD = 64;
+var MAX_NAMED_RULES = 3;
+var READABLE_CLASSES = /* @__PURE__ */ new Set([
+  "STANDARD",
+  "STANDARD_IA",
+  "ONEZONE_IA",
+  "GLACIER_IR",
+  "INTELLIGENT_TIERING"
+]);
+var ARCHIVE_CLASSES = /* @__PURE__ */ new Set(["GLACIER", "DEEP_ARCHIVE"]);
+var INFREQUENT_CLASSES = /* @__PURE__ */ new Set([
+  "STANDARD_IA",
+  "ONEZONE_IA",
+  "GLACIER_IR"
+]);
+var cut = (text, max) => text.length > max ? text.slice(0, max) : text;
+var overlaps = (a, b) => a.startsWith(b) || b.startsWith(a);
+function rulePrefix(rule) {
+  return rule.Filter?.Prefix ?? rule.Filter?.And?.Prefix ?? rule.Prefix ?? "";
+}
+var hasTagFilter = (rule) => rule.Filter?.Tag !== void 0 || (rule.Filter?.And?.Tags?.length ?? 0) > 0;
+var isEnabled = (rule) => rule.Status !== "Disabled";
+function threat(rule) {
+  if (rule.Expiration?.Days !== void 0 || rule.Expiration?.Date !== void 0) {
+    return "expires current objects";
+  }
+  const classes = (rule.Transitions ?? []).map((t) => t.StorageClass);
+  const archive = classes.find((c) => c !== void 0 && ARCHIVE_CLASSES.has(c));
+  if (archive !== void 0) return `moves current objects to ${archive}`;
+  const unknown = (rule.Transitions ?? []).find(
+    (t) => t.StorageClass === void 0 || !READABLE_CLASSES.has(t.StorageClass)
+  );
+  return unknown === void 0 ? void 0 : `moves current objects to ${cut(String(unknown.StorageClass ?? "no storage class"), MAX_FIELD)}, a storage class this check does not know`;
+}
+var label = (rule) => {
+  const id = rule.ID === void 0 ? "" : `${JSON.stringify(cut(rule.ID, MAX_FIELD))} `;
+  return `${id}(prefix ${JSON.stringify(cut(rulePrefix(rule), MAX_FIELD))})`;
+};
+var sitsInside = (rule, prefix) => prefix !== "" && rulePrefix(rule).startsWith(prefix);
+function coversGenerations(rule, prefix) {
+  const own = rulePrefix(rule);
+  if (prefix.startsWith(own)) return true;
+  return !own.slice(prefix.length).startsWith("registry/");
+}
+var ABORT_ADVICE = "No rule aborts incomplete multipart uploads under this prefix; add one (AbortIncompleteMultipartUpload, a few days) so an upload a crashed writer abandoned stops billing for its parts.";
+var INTELLIGENT_TIERING_ADVICE = "A rule moves current objects to INTELLIGENT_TIERING: if the bucket turns on its archive access tiers, an object in one needs a restore before it can be read, so leave them off for this prefix.";
+var INFREQUENT_ADVICE = "A rule moves current objects to an infrequent-access class or GLACIER_IR: they stay readable, but each has a minimum storage duration and a per-GB retrieval fee that reads of the store will pay.";
+function judgeRules(rules, prefix) {
+  const live = rules.filter((r) => isEnabled(r) && overlaps(rulePrefix(r), prefix));
+  const untagged = live.filter((r) => !hasTagFilter(r));
+  const threats = untagged.flatMap((r) => {
+    const how = threat(r);
+    return how === void 0 ? [] : [{ text: `rule ${label(r)} ${how}`, inside: sitsInside(r, prefix) }];
+  });
+  const problems = threats.map((t) => t.text);
+  const transitionsTo = (classes) => untagged.some(
+    (r) => (r.Transitions ?? []).some(
+      (t) => t.StorageClass !== void 0 && classes.has(t.StorageClass)
+    )
+  );
+  const advice = [
+    live.some((r) => r.AbortIncompleteMultipartUpload !== void 0 && coversGenerations(r, prefix)) ? "" : ABORT_ADVICE,
+    transitionsTo(/* @__PURE__ */ new Set(["INTELLIGENT_TIERING"])) ? INTELLIGENT_TIERING_ADVICE : "",
+    transitionsTo(INFREQUENT_CLASSES) ? INFREQUENT_ADVICE : ""
+  ].filter((a) => a !== "").map((a) => ` ${a}`).join("");
+  if (problems.length > 0) {
+    const named = problems.slice(0, MAX_NAMED_RULES).join("; ");
+    const more = problems.length > MAX_NAMED_RULES ? ` and ${problems.length - MAX_NAMED_RULES} more` : "";
+    const quoted = JSON.stringify(cut(prefix, MAX_FIELD));
+    const narrow = `Narrow the rule's prefix to exclude ${quoted}, or restrict it to noncurrent versions.`;
+    const retarget = `A rule that sits inside ${quoted} cannot be narrowed to exclude it: remove it or retarget it to another prefix, or restrict it to noncurrent versions.`;
+    const where = prefix === "" ? "The store has no prefix, so every bucket-wide or prefixed rule can reach it: give the store a prefix, or scope the rule away from its paths." : [
+      threats.some((t) => !t.inside) ? narrow : "",
+      threats.some((t) => t.inside) ? retarget : ""
+    ].filter((x) => x !== "").join(" ");
+    return {
+      status: "problem",
+      detail: `${named}${more}. The store keeps current objects it must be able to read back. ${where}${advice}`
+    };
+  }
+  return {
+    status: "ok",
+    detail: `no enabled lifecycle rule under ${JSON.stringify(cut(prefix, MAX_FIELD))} expires or archives current objects.${advice}`
+  };
+}
+function unchecked(err) {
+  if (err instanceof TransientError2) {
+    return {
+      status: "unchecked",
+      detail: "the read of the bucket lifecycle configuration got no answer in time (readTimeoutMs); run the check again"
+    };
+  }
+  const scrubbed = scrubCredentials(err);
+  if (errorName(scrubbed) === "AccessDenied") {
+    return {
+      status: "unchecked",
+      detail: "the identity may not read the bucket lifecycle configuration: grant s3:GetLifecycleConfiguration on the bucket to check it, or confirm by hand that no rule expires or archives current objects under this prefix"
+    };
+  }
+  const name = cut(String(errorName(scrubbed) ?? "Error"), MAX_FIELD);
+  const raw = scrubbed?.message;
+  const message = typeof raw === "string" ? `: ${raw.slice(0, MAX_MESSAGE)}` : "";
+  return {
+    status: "unchecked",
+    detail: `could not read the bucket lifecycle configuration (${name}${message}); check it by hand`
+  };
+}
+async function checkS3Lifecycle(client, bucket, prefix, readTimeoutMs = 0) {
+  try {
+    const out = await timedRead(
+      "GetBucketLifecycleConfiguration",
+      readTimeoutMs,
+      (options) => client.send(new GetBucketLifecycleConfigurationCommand({ Bucket: bucket }), options)
+    );
+    return judgeRules(out.Rules ?? [], prefix);
+  } catch (err) {
+    try {
+      if (errorName(err) === "NoSuchLifecycleConfiguration") {
+        return judgeRules([], prefix);
+      }
+      return unchecked(err);
+    } catch {
+      return { status: "unchecked", detail: "could not read the bucket lifecycle configuration" };
+    }
+  }
+}
+
+// src/storage.ts
+import {
+  errorKind,
+  IntegrityError,
+  NotFoundError as NotFoundError2,
+  TransientError as TransientError3,
+  ValidationError as ValidationError3,
+  WriteConflictError,
+  concatBytes,
+  normalizeObjectPrefix,
+  parseGenerationFromKey,
+  checkDeleteOptions,
+  requireBool,
+  requirePositiveInt,
+  segmentObjectPrefix,
+  storageObjectKey,
+  toTransient
+} from "@cloudbitmaps/core/driver-kit";
+import { createHash, randomBytes } from "node:crypto";
+import {
+  AbortMultipartUploadCommand,
+  CompleteMultipartUploadCommand,
+  CreateMultipartUploadCommand,
+  DeleteObjectCommand as DeleteObjectCommand2,
+  GetObjectCommand,
+  HeadObjectCommand,
+  ListObjectsV2Command,
+  PutObjectCommand as PutObjectCommand2,
+  UploadPartCommand
+} from "@aws-sdk/client-s3";
+
+// src/s3-errors.ts
+import { ValidationError as ValidationError2 } from "@cloudbitmaps/core/driver-kit";
+function isPreconditionFailed(err) {
+  return errorName(err) === "PreconditionFailed" || httpStatus(err) === 412;
+}
+function isConditionalConflict(err) {
+  return isPreconditionFailed(err) || errorName(err) === "ConditionalRequestConflict" || httpStatus(err) === 409;
+}
+function isThrottle(err) {
+  const status = httpStatus(err);
+  return errorName(err) === "SlowDown" || status === 503 || status === 429;
+}
+function isNoSuchUpload(err) {
+  return errorName(err) === "NoSuchUpload";
+}
+function isMissingBucket(err) {
+  return errorName(err) === "NoSuchBucket";
+}
+function asMissingBucket(err, bucket) {
+  if (!isMissingBucket(err)) return err;
+  return Object.assign(
+    new ValidationError2(
+      `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);
+  return name === "NoSuchKey" || name === "NotFound" || httpStatus(err) === 404;
+}
+function isInvalidRange(err) {
+  return errorName(err) === "InvalidRange" || httpStatus(err) === 416;
+}
+function isClockSkewCorrected(err) {
+  const e = err;
+  return e?.$metadata?.clockSkewCorrected === true;
+}
+function isTransient(err) {
+  if (isConditionalConflict(err) || isNotFound(err) || isInvalidRange(err)) return false;
+  return isThrottle(err) || 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);
+  if (match === null) return void 0;
+  const start = Number(match[1]);
+  const end = Number(match[2]);
+  return Number.isSafeInteger(start) && Number.isSafeInteger(end) ? { start, end } : void 0;
+}
+function totalFromContentRange(contentRange) {
+  if (contentRange === void 0) return void 0;
+  const match = /\/(\d+)\s*$/.exec(contentRange);
+  if (match === null) return void 0;
+  const total = Number(match[1]);
+  return Number.isSafeInteger(total) ? total : void 0;
+}
+
+// src/send-once.ts
+var NO_RETRY = {
+  name: "retryMiddleware",
+  step: "finalizeRequest",
+  priority: "high",
+  override: true
+};
+function sendOnce(client, command) {
+  command.middlewareStack.add((next) => next, NO_RETRY);
+  return client.send(command, {});
+}
+
+// src/bounded-body.ts
+import { NotFoundError } from "@cloudbitmaps/core/driver-kit";
+function destroyBody(body) {
+  body?.destroy?.();
+}
+async function readBounded(body, maxBytes, oversize, advertised) {
+  if (body === void 0) throw new NotFoundError("S3 GetObject returned an empty body");
+  if (advertised !== void 0 && advertised > maxBytes) {
+    destroyBody(body);
+    throw oversize();
+  }
+  if (typeof body[Symbol.asyncIterator] !== "function") {
+    const bytes = await body.transformToByteArray();
+    if (bytes.length > maxBytes) throw oversize();
+    return bytes;
+  }
+  const chunks = [];
+  let total = 0;
+  let done = false;
+  try {
+    for await (const chunk of body) {
+      const piece = typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk;
+      total += piece.length;
+      if (total > maxBytes) throw oversize();
+      chunks.push(piece);
+    }
+    done = true;
+  } finally {
+    if (!done) destroyBody(body);
+  }
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const piece of chunks) {
+    out.set(piece, at);
+    at += piece.length;
+  }
+  return out;
+}
+
 // src/client-probe.ts
 import { DeleteObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
 var PROBE_KEY = "cloudbitmaps-probe";
@@ -542,15 +679,15 @@ var S3_LABELS = /* @__PURE__ */ new Set([
 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);
+var isS3Label = (label2) => S3_LABELS.has(label2) || S3_DASH_REGION_LABEL.test(label2) || S3_EXPRESS_LABEL.test(label2);
 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;
+  labels.forEach((label2, i) => {
+    if (isS3Label(label2)) at = i;
   });
   if (at === -1) return false;
   const rest = labels.slice(at + 1);
@@ -783,7 +920,7 @@ var S3StorageDriver = class {
   }
   async delete(key, options) {
     const objectKey = storageObjectKey(this.prefix, key);
-    const ifVersion = options?.ifVersion;
+    const ifVersion = checkDeleteOptions(options);
     if (ifVersion !== void 0 && this.explicitConditionalDelete !== false) await this.settle();
     const conditional = ifVersion !== void 0 && appliesDeleteIfMatch(this.explicitConditionalDelete, this.facts);
     try {
@@ -927,7 +1064,7 @@ var S3MultipartSink = class {
         })
       );
       if (res2.UploadId === void 0) {
-        throw new TransientError2("S3 CreateMultipartUpload returned no UploadId");
+        throw new TransientError3("S3 CreateMultipartUpload returned no UploadId");
       }
       this.uploadId = res2.UploadId;
     }
@@ -1015,7 +1152,7 @@ var S3MultipartSink = class {
           const stored = await this.storedObject();
           if (stored?.id === this.writeId) return;
           if (stored === void 0 && !isPreconditionFailed(err)) {
-            throw new TransientError2(
+            throw new TransientError3(
               `S3 ${operation}: ${this.objectKey} is not stored, and the first send may still be applying`,
               { cause: err }
             );
@@ -1025,7 +1162,7 @@ var S3MultipartSink = class {
         }
         if (!isThrottle(err)) throw err;
         if (resent >= THROTTLE_RESENDS) {
-          throw new TransientError2(
+          throw new TransientError3(
             `S3 ${operation} was throttled on each of its ${resent + 1} sends; the object may or may not exist`,
             { cause: err }
           );
@@ -1334,6 +1471,48 @@ function emit(sink, event) {
 }
 
 // src/backend.ts
+function checkCredentials(credentials) {
+  if (credentials === void 0) return;
+  if (typeof credentials === "function") {
+    throw new ValidationError5(
+      "S3Storage: `credentials` must be an object of `accessKeyId` and `secretAccessKey`, not a provider function; pass a provider on an S3Client given as `client`"
+    );
+  }
+  const keys = [
+    "accessKeyId",
+    "secretAccessKey",
+    "sessionToken",
+    "$source",
+    "credentialScope",
+    "accountId",
+    "expiration"
+  ];
+  refuseUnknownOptions("S3Storage credentials", credentials, keys);
+  const given = credentials;
+  const needText = (key, value) => {
+    if (typeof value !== "string" || value.trim().length === 0) {
+      throw new ValidationError5(
+        `S3Storage: \`credentials.${key}\` must be a non-empty string; got ${typeof value === "string" ? "an empty string" : value === null || value === void 0 ? String(value) : `a ${typeof value}`}`
+      );
+    }
+  };
+  needText("accessKeyId", given.accessKeyId);
+  needText("secretAccessKey", given.secretAccessKey);
+  if (given.sessionToken !== void 0) needText("sessionToken", given.sessionToken);
+}
+function checkEndpointUrl(endpoint) {
+  let url;
+  try {
+    url = new URL(endpoint);
+  } catch {
+    url = void 0;
+  }
+  if (url === void 0 || !/^https?:$/.test(url.protocol) || url.hostname.length === 0) {
+    throw new ValidationError5(
+      'S3Storage: `endpoint` must be an http or https URL such as "http://localhost:9000"'
+    );
+  }
+}
 var S3_STORAGE_OPTION_KEYS = [
   "bucket",
   "prefix",
@@ -1381,6 +1560,18 @@ var S3Storage = class {
   /** The client both halves share — built here unless one was supplied. */
   client;
   sockets;
+  bucket;
+  /** The key prefix every object sits under: `''`, or `trimmed/`. */
+  keyPrefix;
+  readTimeoutMs;
+  /**
+   * Builds the S3 backend over one bucket, which `bucket` names. Pass `client`, or `region`, `endpoint`, `pathStyle`,
+   * `credentials` and `maxSockets` to have one built, not both. `prefix` puts every object under a key prefix. Throws
+   * `ValidationError` for an unknown option, no bucket, a `now` that is not a function, a client setting beside
+   * `client`, a `maxSockets` (with no `client`) that is not a positive integer, a `partBytes` or `maxObjectBytes` that
+   * is not a positive integer, a `conditionalDelete` that is not a boolean, a `region` or `endpoint` that is empty or not a string, a `pathStyle` that
+   * is not a boolean, `credentials` that are not complete, or an invalid `prefix` or `readTimeoutMs`.
+   */
   constructor(options) {
     refuseUnknownOptions(
       "S3Storage",
@@ -1388,7 +1579,7 @@ var S3Storage = class {
       S3_STORAGE_OPTION_KEYS,
       "an S3 client goes in `client`"
     );
-    if (typeof options.bucket !== "string" || options.bucket.length === 0) {
+    if (typeof options.bucket !== "string" || options.bucket.trim().length === 0) {
       throw new ValidationError5("S3Storage needs a `bucket`: the name of one, a non-empty string");
     }
     if (options.now !== void 0 && typeof options.now !== "function") {
@@ -1403,9 +1594,24 @@ var S3Storage = class {
           `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\``
         );
       }
+      if (typeof options.client.send !== "function") {
+        throw new ValidationError5(
+          "S3Storage: `client` must be an S3Client from @aws-sdk/client-s3 (an object with `send`)"
+        );
+      }
       this.client = options.client;
     } else {
       const maxSockets = requirePositiveInt2("maxSockets", options.maxSockets) ?? DEFAULT_MAX_SOCKETS;
+      const region = options.region;
+      if (region !== void 0 && (typeof region !== "string" || region.trim().length === 0)) {
+        throw new ValidationError5(
+          "S3Storage's `region` must be a non-empty string such as 'us-east-1'"
+        );
+      }
+      const endpoint = requireNonEmptyString("S3Storage: `endpoint`", options.endpoint);
+      if (endpoint !== void 0) checkEndpointUrl(endpoint);
+      requireBool3("S3Storage: `pathStyle`", options.pathStyle);
+      checkCredentials(options.credentials);
       this.client = new S3Client(
         defined({
           credentials: options.credentials,
@@ -1416,6 +1622,9 @@ var S3Storage = class {
       );
       limitSockets(this.client, maxSockets);
     }
+    this.bucket = options.bucket;
+    this.keyPrefix = prefixPart(normalizeObjectPrefix3(options.prefix));
+    this.readTimeoutMs = resolveReadTimeoutMs(options.readTimeoutMs);
     this.sockets = new SocketAdvisory(this.client, options.bucket);
     const shared = {
       client: this.client,
@@ -1444,6 +1653,18 @@ var S3Storage = class {
   attachMetrics(sink) {
     this.sockets.attach(sink);
   }
+  /**
+   * Reads the bucket's lifecycle configuration (one `GetBucketLifecycleConfiguration` request, plus the SDK's own
+   * retries, bounded by `readTimeoutMs` when it is set) and reports a rule that would expire, or move to GLACIER,
+   * DEEP_ARCHIVE or a class it does not know, the current objects under this store's prefix, generations and registry
+   * rows alike. Needs `s3:GetLifecycleConfiguration`, which a load never uses (`store.preflight()`'s
+   * lifecycle step does): without it the
+   * answer is `unchecked`, naming the permission. A missing rule that aborts incomplete multipart uploads is advice in
+   * `detail`, not a problem. Never rejects; a `detail` carries no credential. Rule reading: see the production guide.
+   */
+  checkLifecycle() {
+    return checkS3Lifecycle(this.client, this.bucket, this.keyPrefix, this.readTimeoutMs);
+  }
 };
 export {
   S3Storage