@cloudbitmaps/gcs 0.22.0 → 0.23.0

package/dist/index.js

@@ -2,7 +2,10 @@
 import {
   ValidationError as ValidationError5,
   brandAsBackend,
-  refuseUnknownOptions
+  normalizeObjectPrefix as normalizeObjectPrefix3,
+  prefixPart,
+  refuseUnknownOptions,
+  requireNonEmptyString
 } from "@cloudbitmaps/core/driver-kit";
 import { Storage as GcsClient } from "@google-cloud/storage";
 
@@ -11,111 +14,63 @@ function defined(values) {
   return Object.fromEntries(Object.entries(values).filter(([, v]) => v !== void 0));
 }
 
-// src/storage.ts
-import {
-  errorKind,
-  NotFoundError,
-  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 { once as once2 } from "node:events";
-
-// src/bucket-presence.ts
-import { TransientError } from "@cloudbitmaps/core/driver-kit";
-
-// src/gcs-errors.ts
-import {
-  ValidationError,
-  isTransportFault as isNodeTransportFault
-} from "@cloudbitmaps/core/driver-kit";
-function httpStatus(err) {
-  const e = err;
-  if (typeof e?.code === "number") return e.code;
-  if (typeof e?.response?.status === "number") return e.response.status;
-  return void 0;
-}
-function networkCode(err) {
-  const code = err?.code;
-  return typeof code === "string" ? code : void 0;
-}
-function isPreconditionFailed(err) {
-  return httpStatus(err) === 412;
-}
-function isThrottle(err) {
-  const status = httpStatus(err);
-  return status === 429 || status === 503;
-}
-function isNotFound(err) {
-  return httpStatus(err) === 404 && !isMissingBucket(err);
-}
-function isMissingBucket(err) {
-  if (httpStatus(err) !== 404) return false;
-  const e = err;
-  const says = (m) => typeof m === "string" && /bucket does not exist/i.test(m);
-  if (says(e.message)) return true;
-  return Array.isArray(e.errors) && e.errors.some((inner) => says(inner?.message));
-}
-function missingBucketError(bucket, cause) {
-  return Object.assign(
-    new ValidationError(
-      `the GCS bucket does not exist: ${bucket}; check the bucket name and the project the client is built for`
-    ),
-    { cause }
-  );
-}
-function asMissingBucket(err, bucket) {
-  return isMissingBucket(err) ? missingBucketError(bucket, err) : err;
-}
-function isInvalidRange(err) {
-  return httpStatus(err) === 416;
-}
-var SDK_RETRIED_STATUSES = [408, 429, 500, 502, 503, 504];
-function isSdkConnectionProblem(reason) {
-  return reason.includes("eai_again") || reason === "econnreset" || reason === "unexpected connection closure" || reason === "epipe" || reason === "socket connection timeout";
-}
-function isConnectionFault(err) {
-  return isNodeTransportFault(err) || networkCode(err) === "ERR_STREAM_PREMATURE_CLOSE";
+// src/read-timeout.ts
+import { 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 (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > MAX_TIMER_MS) {
+    throw new ValidationError(
+      `readTimeoutMs must be a non-negative safe integer no larger than ${MAX_TIMER_MS}; got ${describe(value)}`
+    );
+  }
+  return value;
 }
-function isTransportFault(err) {
-  return httpStatus(err) === void 0 && isConnectionFault(err);
+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;
 }
-function isDownloadRetryable(err) {
-  if (err === null || typeof err !== "object") return false;
-  if (isTransportFault(err)) return true;
-  const e = err;
-  if (typeof e.code === "number" && SDK_RETRIED_STATUSES.includes(e.code)) return true;
-  if (typeof e.code === "string") {
-    if (SDK_RETRIED_STATUSES.map(String).includes(e.code)) return true;
-    if (isSdkConnectionProblem(e.code.toLowerCase())) return true;
+var ReadTimedOut = class extends Error {
+  code = "ETIMEDOUT";
+  constructor(read, ms, cause) {
+    super(`GCS ${read} timed out after ${ms} ms`, cause === void 0 ? void 0 : { cause });
+    this.name = "ReadTimedOut";
   }
-  if (Array.isArray(e.errors)) {
-    for (const inner of e.errors) {
-      const reason = inner?.reason?.toString().toLowerCase();
-      if (reason !== void 0 && isSdkConnectionProblem(reason)) return true;
-    }
+};
+var Deadline = class {
+  constructor(ms, read) {
+    this.ms = ms;
+    this.read = read;
+    this.endsAt = performance.now() + ms;
   }
-  return false;
-}
-function isTransient(err) {
-  if (isPreconditionFailed(err) || isNotFound(err) || isInvalidRange(err)) return false;
-  const status = httpStatus(err);
-  if (status === 408 || status === 429 || status !== void 0 && status >= 500 && status < 600)
-    return true;
-  return isConnectionFault(err);
+  ms;
+  read;
+  endsAt;
+  /** What is left of it, in milliseconds: 0 once it has passed. */
+  remaining() {
+    return Math.max(0, this.endsAt - performance.now());
+  }
+  /** The error a read fails with once this has passed; `cause` is the last attempt's own error, if one failed. */
+  expired(cause) {
+    return new ReadTimedOut(this.read, this.ms, cause);
+  }
+};
+function startDeadline(ms, read) {
+  return ms === 0 ? void 0 : new Deadline(ms, read);
 }
-function transientFaultMessage(err) {
-  const e = err;
-  return `transient GCS fault: ${String(e?.code ?? e?.name ?? "unknown")}`;
+function withDeadline(send, deadline) {
+  if (deadline === void 0) return send();
+  if (deadline.remaining() === 0) return Promise.reject(deadline.expired());
+  const request = send();
+  let timer;
+  const timedOut = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(deadline.expired()), deadline.remaining());
+  });
+  return Promise.race([request, timedOut]).finally(() => clearTimeout(timer));
 }
 
 // src/scrub-error.ts
@@ -475,6 +430,219 @@ function scrubCredentials(err) {
   return ctx.changed && copy !== OMIT ? copy : err;
 }
 
+// src/lifecycle.ts
+var MAX_MESSAGE = 200;
+var MAX_FIELD = 64;
+var MAX_CONDITION = 120;
+var MAX_NAMED_RULES = 3;
+var cut = (text, max) => text.length > max ? text.slice(0, max) : text;
+var SAFE_ACTIONS = /* @__PURE__ */ new Set([
+  "SetStorageClass",
+  "AbortIncompleteMultipartUpload"
+]);
+var NAME_SUFFIXES = [".crbm", ".reg"];
+var prefixRelated = (a, b) => a.startsWith(b) || b.startsWith(a);
+var suffixRelated = (a, b) => a.endsWith(b) || b.endsWith(a);
+var strings = (value) => Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+var record = (value) => typeof value === "object" && value !== null ? value : {};
+var NONCURRENT_ONLY = ["daysSinceNoncurrentTime", "noncurrentTimeBefore"];
+var metByLiveObject = (value) => typeof value !== "number" || value < 1;
+var actionOf = (rule) => {
+  const type = record(record(rule).action).type;
+  return typeof type === "string" && type !== "" ? type : void 0;
+};
+var isRule = (rule) => typeof rule === "object" && rule !== null;
+function deletesOurs(rule, prefix) {
+  if (!isRule(rule)) return false;
+  const type = actionOf(rule);
+  if (type !== void 0 && SAFE_ACTIONS.has(type)) return false;
+  const when = record(record(rule).condition);
+  if (when.isLive === false) return false;
+  if (NONCURRENT_ONLY.some((key) => when[key] !== void 0)) return false;
+  if (!metByLiveObject(when.numNewerVersions)) return false;
+  const prefixes = strings(when.matchesPrefix);
+  if (prefixes.length > 0 && !prefixes.some((p) => prefixRelated(p, prefix))) return false;
+  const suffixes = strings(when.matchesSuffix);
+  return suffixes.length === 0 || suffixes.some((s) => NAME_SUFFIXES.some((ours) => suffixRelated(s, ours)));
+}
+function sitsInside(rule, prefix) {
+  const prefixes = strings(record(record(rule).condition).matchesPrefix);
+  return prefix !== "" && prefixes.length > 0 && !prefixes.some((p) => p !== prefix && prefix.startsWith(p));
+}
+function judgeMetadata(metadata, prefix) {
+  const rules = record(record(metadata).lifecycle).rule;
+  const found = (Array.isArray(rules) ? rules : []).filter(
+    (r) => deletesOurs(r, prefix)
+  );
+  if (found.length > 0) {
+    const named = found.slice(0, MAX_NAMED_RULES).map(
+      (r) => `${cut(actionOf(r) ?? "no action type", MAX_FIELD)} when ${cut(JSON.stringify(record(r).condition ?? {}), MAX_CONDITION)}`
+    ).join("; ");
+    const more = found.length > MAX_NAMED_RULES ? ` and ${found.length - MAX_NAMED_RULES} more` : "";
+    const quoted = JSON.stringify(cut(prefix, MAX_FIELD));
+    const narrow = `Narrow the rule with matchesPrefix 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 a rule on any prefix can reach it: give the store a prefix, or scope the rule away from its paths." : [
+      found.some((r) => !sitsInside(r, prefix)) ? narrow : "",
+      found.some((r) => sitsInside(r, prefix)) ? retarget : ""
+    ].filter((x) => x !== "").join(" ");
+    return {
+      status: "problem",
+      detail: `${found.length} bucket lifecycle rule(s) with a Delete action, or one this check does not know, can match objects under ${quoted}: ${named}${more}. The store keeps current objects it must be able to read back. ${where}`
+    };
+  }
+  return {
+    status: "ok",
+    detail: `no bucket lifecycle rule deletes live objects under ${JSON.stringify(cut(prefix, MAX_FIELD))}`
+  };
+}
+function unchecked(err) {
+  if (err instanceof ReadTimedOut) {
+    return {
+      status: "unchecked",
+      detail: "the read of the bucket metadata got no answer in time (readTimeoutMs); run the check again"
+    };
+  }
+  const scrubbed = scrubCredentials(err);
+  const { code, message, name } = record(scrubbed);
+  if (code === 403) {
+    return {
+      status: "unchecked",
+      detail: "the identity may not read the bucket metadata: grant storage.buckets.get on the bucket to check its lifecycle rules, or confirm by hand that no rule deletes current objects under this prefix"
+    };
+  }
+  const shown = typeof message === "string" ? `: ${message.slice(0, MAX_MESSAGE)}` : "";
+  const label = typeof name === "string" ? cut(name, MAX_FIELD) : "Error";
+  const status = typeof code === "number" ? ` ${code}` : "";
+  return {
+    status: "unchecked",
+    detail: `could not read the bucket metadata (${label}${status}${shown}); check the lifecycle rules by hand`
+  };
+}
+async function checkGcsLifecycle(client, bucket, prefix, readTimeoutMs = 0) {
+  try {
+    const [metadata] = await withDeadline(
+      () => client.bucket(bucket).getMetadata(),
+      startDeadline(readTimeoutMs, "bucket metadata read")
+    );
+    return judgeMetadata(metadata, prefix);
+  } catch (err) {
+    try {
+      return unchecked(err);
+    } catch {
+      return { status: "unchecked", detail: "could not read the bucket metadata" };
+    }
+  }
+}
+
+// src/storage.ts
+import {
+  errorKind,
+  NotFoundError,
+  TransientError as TransientError2,
+  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 { once as once2 } from "node:events";
+
+// src/bucket-presence.ts
+import { TransientError } from "@cloudbitmaps/core/driver-kit";
+
+// src/gcs-errors.ts
+import {
+  ValidationError as ValidationError2,
+  isTransportFault as isNodeTransportFault
+} from "@cloudbitmaps/core/driver-kit";
+function httpStatus(err) {
+  const e = err;
+  if (typeof e?.code === "number") return e.code;
+  if (typeof e?.response?.status === "number") return e.response.status;
+  return void 0;
+}
+function networkCode(err) {
+  const code = err?.code;
+  return typeof code === "string" ? code : void 0;
+}
+function isPreconditionFailed(err) {
+  return httpStatus(err) === 412;
+}
+function isThrottle(err) {
+  const status = httpStatus(err);
+  return status === 429 || status === 503;
+}
+function isNotFound(err) {
+  return httpStatus(err) === 404 && !isMissingBucket(err);
+}
+function isMissingBucket(err) {
+  if (httpStatus(err) !== 404) return false;
+  const e = err;
+  const says = (m) => typeof m === "string" && /bucket does not exist/i.test(m);
+  if (says(e.message)) return true;
+  return Array.isArray(e.errors) && e.errors.some((inner) => says(inner?.message));
+}
+function missingBucketError(bucket, cause) {
+  return Object.assign(
+    new ValidationError2(
+      `the GCS bucket does not exist: ${bucket}; check the bucket name and the project the client is built for`
+    ),
+    { cause }
+  );
+}
+function asMissingBucket(err, bucket) {
+  return isMissingBucket(err) ? missingBucketError(bucket, err) : err;
+}
+function isInvalidRange(err) {
+  return httpStatus(err) === 416;
+}
+var SDK_RETRIED_STATUSES = [408, 429, 500, 502, 503, 504];
+function isSdkConnectionProblem(reason) {
+  return reason.includes("eai_again") || reason === "econnreset" || reason === "unexpected connection closure" || reason === "epipe" || reason === "socket connection timeout";
+}
+function isConnectionFault(err) {
+  return isNodeTransportFault(err) || networkCode(err) === "ERR_STREAM_PREMATURE_CLOSE";
+}
+function isTransportFault(err) {
+  return httpStatus(err) === void 0 && isConnectionFault(err);
+}
+function isDownloadRetryable(err) {
+  if (err === null || typeof err !== "object") return false;
+  if (isTransportFault(err)) return true;
+  const e = err;
+  if (typeof e.code === "number" && SDK_RETRIED_STATUSES.includes(e.code)) return true;
+  if (typeof e.code === "string") {
+    if (SDK_RETRIED_STATUSES.map(String).includes(e.code)) return true;
+    if (isSdkConnectionProblem(e.code.toLowerCase())) return true;
+  }
+  if (Array.isArray(e.errors)) {
+    for (const inner of e.errors) {
+      const reason = inner?.reason?.toString().toLowerCase();
+      if (reason !== void 0 && isSdkConnectionProblem(reason)) return true;
+    }
+  }
+  return false;
+}
+function isTransient(err) {
+  if (isPreconditionFailed(err) || isNotFound(err) || isInvalidRange(err)) return false;
+  const status = httpStatus(err);
+  if (status === 408 || status === 429 || status !== void 0 && status >= 500 && status < 600)
+    return true;
+  return isConnectionFault(err);
+}
+function transientFaultMessage(err) {
+  const e = err;
+  return `transient GCS fault: ${String(e?.code ?? e?.name ?? "unknown")}`;
+}
+
 // src/bucket-presence.ts
 var BucketPresence = class {
   constructor(storage, bucket) {
@@ -520,65 +688,6 @@ var BucketPresence = class {
   }
 };
 
-// src/read-timeout.ts
-import { 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 (typeof value !== "number" || !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;
-}
-var ReadTimedOut = class extends Error {
-  code = "ETIMEDOUT";
-  constructor(read, ms, cause) {
-    super(`GCS ${read} timed out after ${ms} ms`, cause === void 0 ? void 0 : { cause });
-    this.name = "ReadTimedOut";
-  }
-};
-var Deadline = class {
-  constructor(ms, read) {
-    this.ms = ms;
-    this.read = read;
-    this.endsAt = performance.now() + ms;
-  }
-  ms;
-  read;
-  endsAt;
-  /** What is left of it, in milliseconds: 0 once it has passed. */
-  remaining() {
-    return Math.max(0, this.endsAt - performance.now());
-  }
-  /** The error a read fails with once this has passed; `cause` is the last attempt's own error, if one failed. */
-  expired(cause) {
-    return new ReadTimedOut(this.read, this.ms, cause);
-  }
-};
-function startDeadline(ms, read) {
-  return ms === 0 ? void 0 : new Deadline(ms, read);
-}
-function withDeadline(send, deadline) {
-  if (deadline === void 0) return send();
-  if (deadline.remaining() === 0) return Promise.reject(deadline.expired());
-  const request = send();
-  let timer;
-  const timedOut = new Promise((_, reject) => {
-    timer = setTimeout(() => reject(deadline.expired()), deadline.remaining());
-  });
-  return Promise.race([request, timedOut]).finally(() => clearTimeout(timer));
-}
-
 // src/download-retry.ts
 var RETRIES = 3;
 var BASE_DELAY_MS = 100;
@@ -932,7 +1041,7 @@ var GcsStorageDriver = class {
   }
   async delete(key, options) {
     const objectName = storageObjectKey(this.prefix, key);
-    const ifVersion = options?.ifVersion;
+    const ifVersion = checkDeleteOptions(options);
     const conditional = ifVersion !== void 0 && this.conditionalDelete;
     try {
       await this.file(objectName).delete(
@@ -1040,6 +1149,10 @@ var GcsUploadSink = class _GcsUploadSink {
   bufferedLen = 0;
   stream;
   // set once we cross the threshold → resumable mode
+  /** The SDK's resumable upload under {@link stream}, which {@link abort} ends with an error: see there. */
+  upload;
+  /** Set by {@link abort}: the held upload starts no request from then on. */
+  abandoned = false;
   done;
   failure;
   static WRITE_OPTS = {
@@ -1080,6 +1193,7 @@ var GcsUploadSink = class _GcsUploadSink {
   }
   /** Cross into resumable streaming: open the stream, flush the buffered bytes, keep only ~one threshold resident. */
   startResumable() {
+    this.holdUpload();
     const stream = this.file.createWriteStream({ resumable: true, ...this.tagged() });
     this.stream = stream;
     this.done = once2(stream, "finish");
@@ -1145,8 +1259,56 @@ var GcsUploadSink = class _GcsUploadSink {
       throw err;
     }
   }
+  /**
+   * Keep the SDK's resumable upload, the writable its write stream pipes into, so {@link abort} can end its request.
+   * The SDK hands it to the stream's duplex through `setWritable` in `startResumableUpload_`, a method of the `File`
+   * its types declare; this wraps that method on this sink's own `File`, which no other write shares. Where the method
+   * or the duplex's `setWritable` is missing, the SDK runs unchanged, nothing is kept, and an abort destroys the
+   * stream alone, as it did before.
+   */
+  holdUpload() {
+    const file = this.file;
+    const start = file.startResumableUpload_;
+    if (typeof start !== "function") return;
+    file.startResumableUpload_ = (dup, options) => {
+      const setWritable = dup.setWritable;
+      if (typeof setWritable === "function") {
+        dup.setWritable = (writable) => {
+          this.hold(writable);
+          setWritable.call(dup, writable);
+        };
+      }
+      start.call(file, dup, options);
+    };
+  }
+  /**
+   * Keep `upload`, and let it start no request once this sink is abandoned. The SDK registers the listener that
+   * aborts an upload's request only as that request starts, after the session is created, so an upload abandoned
+   * before then would start its request anyway, with nothing left to end it. Each request that sends the upload's
+   * bytes, its first and every retry, begins in `startUploading`, a public method of the SDK's `Upload`. On an
+   * abandoned upload it resolves at once: the upload is destroyed already, and some of the SDK's callers do not
+   * catch a rejection.
+   */
+  hold(upload) {
+    this.upload = upload;
+    const held = upload;
+    const startUploading = held.startUploading;
+    if (typeof startUploading !== "function") return;
+    held.startUploading = () => this.abandoned ? Promise.resolve() : startUploading.call(held);
+  }
+  /**
+   * End an upload that will not be committed. Destroying the write stream alone leaves the resumable upload's request
+   * open: the SDK destroys its upload with no error, aborts the request only when the upload errors, and its request
+   * body waits for bytes that never come, so the socket stays open and the process alive until the service drops the
+   * connection. So the upload is destroyed with an error first, which aborts its request; the body was never ended, so
+   * no object is finalized. An upload whose request has not started yet starts none: see {@link hold}. The error is
+   * the sink's own and reaches no caller.
+   */
   async abort() {
-    if (this.stream !== void 0 && !this.stream.destroyed) this.stream.destroy();
+    this.abandoned = true;
+    const abandoned = new Error("the upload was abandoned before its object was committed");
+    if (this.upload !== void 0 && !this.upload.destroyed) this.upload.destroy(abandoned);
+    if (this.stream !== void 0 && !this.stream.destroyed) this.stream.destroy(abandoned);
   }
 };
 
@@ -1452,6 +1614,17 @@ var GcsStorage = class {
   registry;
   /** The client both halves share — built here unless one was supplied. */
   client;
+  bucket;
+  /** The name prefix every object sits under: `''`, or `trimmed/`. */
+  keyPrefix;
+  readTimeoutMs;
+  /**
+   * Builds the GCS backend over one bucket, which `bucket` names. Pass `client`, or `projectId` and `apiEndpoint` to
+   * have one built, not both. `prefix` puts every object under a name prefix. Throws `ValidationError` for an unknown
+   * option, no bucket, a `now` that is not a function, a client setting beside `client`, a `maxObjectBytes` or
+   * `simpleUploadThresholdBytes` that is not a positive integer, a `conditionalDelete` that is not a boolean, an
+   * empty or non-string `apiEndpoint` or `projectId`, or an invalid `prefix` or `readTimeoutMs`.
+   */
   constructor(options) {
     let readClient;
     refuseUnknownOptions(
@@ -1460,7 +1633,7 @@ var GcsStorage = class {
       GCS_STORAGE_OPTION_KEYS,
       "a @google-cloud/storage 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("GcsStorage needs a `bucket`: the name of one, a non-empty string");
     }
     if (options.now !== void 0 && typeof options.now !== "function") {
@@ -1478,11 +1651,21 @@ var GcsStorage = class {
       this.client = options.client;
       readClient = downloadClient(options.client, true);
     } else {
+      const apiEndpoint = requireNonEmptyString("GcsStorage: `apiEndpoint`", options.apiEndpoint);
+      if (apiEndpoint !== void 0 && /^[a-z][a-z0-9+.-]*:\/*$/i.test(apiEndpoint.trim())) {
+        throw new ValidationError5(
+          'GcsStorage: `apiEndpoint` must name a host, such as "http://localhost:4443" or "storage.googleapis.com"'
+        );
+      }
+      requireNonEmptyString("GcsStorage: `projectId`", options.projectId);
       this.client = new GcsClient(
         defined({ projectId: options.projectId, apiEndpoint: options.apiEndpoint })
       );
       readClient = downloadClient(this.client, false);
     }
+    this.bucket = options.bucket;
+    this.keyPrefix = prefixPart(normalizeObjectPrefix3(options.prefix));
+    this.readTimeoutMs = resolveReadTimeoutMs(options.readTimeoutMs);
     const shared = {
       storage: this.client,
       readStorage: readClient,
@@ -1503,6 +1686,17 @@ var GcsStorage = class {
     });
     brandAsBackend(this);
   }
+  /**
+   * Reads the bucket's metadata (one request, plus the SDK's own retries, bounded by `readTimeoutMs` when it is set) and
+   * reports a lifecycle rule with a `Delete` action (or one it does not know) that applies to live
+   * objects whose names can be this store's: generations and registry rows alike. Needs `storage.buckets.get`, which
+   * a load never uses (`store.preflight()`'s lifecycle step does) and `roles/storage.objectAdmin` does not include: without it the answer is
+   * `unchecked`, naming the permission. Never rejects; a `detail` carries no credential. Rule reading: see the
+   * production guide.
+   */
+  checkLifecycle() {
+    return checkGcsLifecycle(this.client, this.bucket, this.keyPrefix, this.readTimeoutMs);
+  }
 };
 export {
   GcsStorage