@cloudbitmaps/gcs 0.18.2 → 0.19.0

package/dist/index.js

@@ -1,11 +1,11 @@
 // src/backend.ts
-import { ValidationError as ValidationError5, brandAsBackend } from "@cloudbitmaps/core/driver-kit";
+import { ValidationError as ValidationError6, brandAsBackend } from "@cloudbitmaps/core/driver-kit";
 import { Storage as GcsClient } from "@google-cloud/storage";
 
 // src/storage.ts
 import {
   NotFoundError,
-  TransientError,
+  TransientError as TransientError2,
   ValidationError as ValidationError3,
   WriteConflictError,
   isNotFoundError,
@@ -15,33 +15,8 @@ import {
 import { createHash, randomBytes } from "node:crypto";
 import { once as once2 } from "node:events";
 
-// 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 storageObjectName(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 parseGenerationFromName(segmentPrefix, objectName) {
-  if (!objectName.startsWith(segmentPrefix) || !objectName.endsWith(SUFFIX)) return null;
-  const middle = objectName.slice(segmentPrefix.length, objectName.length - SUFFIX.length);
-  if (!/^(0|[1-9]\d*)$/.test(middle)) return null;
-  const generation = Number(middle);
-  return Number.isSafeInteger(generation) ? generation : null;
-}
+// src/bucket-presence.ts
+import { TransientError } from "@cloudbitmaps/core/driver-kit";
 
 // src/gcs-errors.ts
 function httpStatus(err) {
@@ -62,7 +37,14 @@ function isThrottle(err) {
   return status === 429 || status === 503;
 }
 function isNotFound(err) {
-  return httpStatus(err) === 404;
+  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 isInvalidRange(err) {
   return httpStatus(err) === 416;
@@ -111,7 +93,160 @@ function isTransient(err) {
   if (status === 408 || status === 429 || status !== void 0 && status >= 500 && status < 600)
     return true;
   const net = networkCode(err);
-  return net === "ECONNRESET" || net === "ETIMEDOUT" || net === "ECONNREFUSED" || net === "EPIPE" || net === "EAI_AGAIN" || net === "ENOTFOUND";
+  return net !== void 0 && TRANSPORT_CODES.has(net);
+}
+
+// src/scrub-error.ts
+var DROPPED = /* @__PURE__ */ new Set([
+  "request",
+  "agent",
+  "socket",
+  "_httpMessage",
+  "connection",
+  "req",
+  "res",
+  "config"
+]);
+var CREDENTIAL_NAME = /^(?:proxy-)?authorization$|^cookie$|^set-cookie$|^x-api-key$/i;
+var CREDENTIAL_LINES = /^((?:proxy-)?authorization|cookie|set-cookie|x-api-key):[^\r\n]*/gim;
+var REDACTED = "[redacted]";
+var isPlain = (value) => {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+};
+function responseSummary(response) {
+  const out = {};
+  for (const key of ["status", "statusText"]) {
+    const value = response[key];
+    if (typeof value === "number" || typeof value === "string") out[key] = value;
+  }
+  return out;
+}
+function clean(value, copies) {
+  if (typeof value === "string") return value.replace(CREDENTIAL_LINES, `$1: ${REDACTED}`);
+  if (typeof value !== "object" || value === null) {
+    return typeof value === "function" || typeof value === "symbol" ? void 0 : value;
+  }
+  if (copies.has(value)) return copies.get(value);
+  if (Array.isArray(value)) {
+    const list = [];
+    copies.set(value, list);
+    for (const item of value) list.push(clean(item, copies));
+    return list;
+  }
+  const isError = value instanceof Error;
+  if (!isError && !isPlain(value)) return void 0;
+  const copy = Object.create(Object.getPrototypeOf(value));
+  copies.set(value, copy);
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key === "string" && DROPPED.has(key)) continue;
+    let held;
+    try {
+      held = value[key];
+    } catch {
+      continue;
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    let kept;
+    if (typeof key === "string" && CREDENTIAL_NAME.test(key)) kept = held == null ? held : REDACTED;
+    else if (key === "response" && typeof held === "object" && held !== null) {
+      kept = responseSummary(held);
+    } else kept = clean(held, copies);
+    if (kept === void 0 && held !== void 0) continue;
+    Object.defineProperty(copy, key, {
+      value: kept,
+      writable: true,
+      configurable: true,
+      enumerable: descriptor?.enumerable ?? true
+    });
+  }
+  return copy;
+}
+function holdsTransport(err, seen) {
+  if (seen.has(err)) return false;
+  seen.add(err);
+  if (Object.getOwnPropertyNames(err).some((key) => DROPPED.has(key) || key === "response")) {
+    return true;
+  }
+  const cause = err.cause;
+  return typeof cause === "object" && cause !== null && holdsTransport(cause, seen);
+}
+function scrubCredentials(err) {
+  if (typeof err !== "object" || err === null) return err;
+  return holdsTransport(err, /* @__PURE__ */ new Set()) ? clean(err, /* @__PURE__ */ new WeakMap()) : err;
+}
+
+// src/bucket-presence.ts
+var BucketPresence = class {
+  constructor(storage, bucket) {
+    this.storage = storage;
+    this.bucket = bucket;
+  }
+  storage;
+  bucket;
+  settled = false;
+  asking;
+  /** Resolve when a 404 can be read as an object's; reject when the bucket does not exist or the listing failed in transit. */
+  async confirm() {
+    if (this.settled) return;
+    this.asking ??= this.ask().finally(() => {
+      this.asking = void 0;
+    });
+    return this.asking;
+  }
+  async ask() {
+    let failure;
+    try {
+      await this.storage.bucket(this.bucket).getFiles({ maxResults: 1, autoPaginate: false });
+    } catch (raised) {
+      failure = { raised };
+    }
+    if (failure !== void 0) {
+      const err = scrubCredentials(failure.raised);
+      const status = err?.code;
+      if (status === 404) {
+        throw new Error(`the GCS bucket does not exist: ${this.bucket}`, { cause: err });
+      }
+      if (isTransient(err)) {
+        throw new TransientError(
+          `transient GCS fault confirming the bucket exists: ${String(status)}`,
+          {
+            cause: err
+          }
+        );
+      }
+      if (status !== 403) return;
+    }
+    this.settled = true;
+  }
+};
+
+// 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 storageObjectName(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 parseGenerationFromName(segmentPrefix, objectName) {
+  if (!objectName.startsWith(segmentPrefix) || !objectName.endsWith(SUFFIX)) return null;
+  const middle = objectName.slice(segmentPrefix.length, objectName.length - SUFFIX.length);
+  if (!/^(0|[1-9]\d*)$/.test(middle)) return null;
+  const generation = Number(middle);
+  return Number.isSafeInteger(generation) ? generation : null;
 }
 
 // src/read-timeout.ts
@@ -196,86 +331,6 @@ async function retryDownload(download, deadline) {
   }
 }
 
-// src/scrub-error.ts
-var DROPPED = /* @__PURE__ */ new Set([
-  "request",
-  "agent",
-  "socket",
-  "_httpMessage",
-  "connection",
-  "req",
-  "res",
-  "config"
-]);
-var CREDENTIAL_NAME = /^(?:proxy-)?authorization$|^cookie$|^set-cookie$|^x-api-key$/i;
-var CREDENTIAL_LINES = /^((?:proxy-)?authorization|cookie|set-cookie|x-api-key):[^\r\n]*/gim;
-var REDACTED = "[redacted]";
-var isPlain = (value) => {
-  const proto = Object.getPrototypeOf(value);
-  return proto === Object.prototype || proto === null;
-};
-function responseSummary(response) {
-  const out = {};
-  for (const key of ["status", "statusText"]) {
-    const value = response[key];
-    if (typeof value === "number" || typeof value === "string") out[key] = value;
-  }
-  return out;
-}
-function clean(value, copies) {
-  if (typeof value === "string") return value.replace(CREDENTIAL_LINES, `$1: ${REDACTED}`);
-  if (typeof value !== "object" || value === null) {
-    return typeof value === "function" || typeof value === "symbol" ? void 0 : value;
-  }
-  if (copies.has(value)) return copies.get(value);
-  if (Array.isArray(value)) {
-    const list = [];
-    copies.set(value, list);
-    for (const item of value) list.push(clean(item, copies));
-    return list;
-  }
-  const isError = value instanceof Error;
-  if (!isError && !isPlain(value)) return void 0;
-  const copy = Object.create(Object.getPrototypeOf(value));
-  copies.set(value, copy);
-  for (const key of Reflect.ownKeys(value)) {
-    if (typeof key === "string" && DROPPED.has(key)) continue;
-    let held;
-    try {
-      held = value[key];
-    } catch {
-      continue;
-    }
-    const descriptor = Object.getOwnPropertyDescriptor(value, key);
-    let kept;
-    if (typeof key === "string" && CREDENTIAL_NAME.test(key)) kept = held == null ? held : REDACTED;
-    else if (key === "response" && typeof held === "object" && held !== null) {
-      kept = responseSummary(held);
-    } else kept = clean(held, copies);
-    if (kept === void 0 && held !== void 0) continue;
-    Object.defineProperty(copy, key, {
-      value: kept,
-      writable: true,
-      configurable: true,
-      enumerable: descriptor?.enumerable ?? true
-    });
-  }
-  return copy;
-}
-function holdsTransport(err, seen) {
-  if (seen.has(err)) return false;
-  seen.add(err);
-  if (Object.getOwnPropertyNames(err).some((key) => DROPPED.has(key) || key === "response")) {
-    return true;
-  }
-  const cause = err.cause;
-  return typeof cause === "object" && cause !== null && holdsTransport(cause, seen);
-}
-function scrubCredentials(err) {
-  if (typeof err !== "object" || err === null) return err;
-  return holdsTransport(err, /* @__PURE__ */ new Set()) ? clean(err, /* @__PURE__ */ new WeakMap()) : err;
-}
-
 // src/send-once.ts
 import { once } from "node:events";
 async function saveOnce(file, body, options) {
@@ -373,6 +428,7 @@ var GcsStorageDriver = class {
   threshold;
   readTimeoutMs;
   clock;
+  presence;
   constructor(options) {
     this.storage = options.storage;
     this.clock = options.clock ?? REAL_TIME;
@@ -387,9 +443,15 @@ var GcsStorageDriver = class {
         throw new ValidationError3(`${name} must be a positive safe integer; got ${value}`);
       }
     }
+    if (options.maxObjectBytes !== void 0 && options.maxObjectBytes > 5 * 1024 ** 4) {
+      throw new ValidationError3(
+        `maxObjectBytes must be at most GCS's 5 TiB object limit (${5 * 1024 ** 4}); got ${options.maxObjectBytes}`
+      );
+    }
     this.maxObjectBytes = options.maxObjectBytes ?? DEFAULT_MAX_OBJECT_BYTES;
     this.threshold = options.simpleUploadThresholdBytes ?? DEFAULT_UPLOAD_THRESHOLD_BYTES;
     this.readTimeoutMs = resolveReadTimeoutMs(options.readTimeoutMs);
+    this.presence = new BucketPresence(this.storage, this.bucket);
   }
   capabilities() {
     return { rangeRead: true, maxObjectBytes: this.maxObjectBytes, conditionalPut: true };
@@ -448,7 +510,7 @@ var GcsStorageDriver = class {
       this.checkRange(res, key, offset, length);
       return res.bytes;
     } catch (err) {
-      throw this.mapReadError(err, key);
+      throw await this.readFailure(err, key);
     }
   }
   /**
@@ -524,7 +586,7 @@ var GcsStorageDriver = class {
       }
       return { bytes: res.bytes, size: this.tailSize(res, maxBytes, key) };
     } catch (err) {
-      throw this.mapReadError(err, key);
+      throw await this.readFailure(err, key);
     }
   }
   /**
@@ -575,8 +637,9 @@ var GcsStorageDriver = class {
   }
   async delete(key) {
     try {
-      await this.file(storageObjectName(this.prefix, key)).delete({ ignoreNotFound: true });
+      await this.file(storageObjectName(this.prefix, key)).delete();
     } catch (err) {
+      if (isNotFound(err)) return this.presence.confirm();
       throw this.mapError(err);
     }
   }
@@ -595,6 +658,11 @@ var GcsStorageDriver = class {
       }
     }
   }
+  /** A read's error, once a 404 is known to be the object's and not the bucket's ({@link BucketPresence}). */
+  async readFailure(err, key) {
+    if (isNotFound(err)) await this.presence.confirm();
+    return this.mapReadError(err, key);
+  }
   /** Map GCS read errors to the driver vocabulary; pass everything else through {@link mapError}. */
   mapReadError(err, key) {
     err = scrubCredentials(err);
@@ -604,9 +672,9 @@ var GcsStorageDriver = class {
     if (isInvalidRange(err)) {
       return new ValidationError3(`range out of bounds for ${key.segment}.${key.generation}`);
     }
-    if (err instanceof ReadTimedOut) return new TransientError(err.message, { cause: err });
+    if (err instanceof ReadTimedOut) return new TransientError2(err.message, { cause: err });
     if (isTransportFault(err)) {
-      return new TransientError(
+      return new TransientError2(
         `transient GCS fault: ${String(err.code)}`,
         {
           cause: err
@@ -624,7 +692,7 @@ var GcsStorageDriver = class {
   mapError(err) {
     err = scrubCredentials(err);
     if (isTransient(err)) {
-      return new TransientError(
+      return new TransientError2(
         `transient GCS fault: ${err?.code ?? "unknown"}`,
         { cause: err }
       );
@@ -689,10 +757,10 @@ var GcsUploadSink = class _GcsUploadSink {
     }
     this.hash.update(bytes);
     if (this.stream !== void 0) {
-      if (!this.stream.write(bytes)) await once2(this.stream, "drain");
+      if (!this.stream.write(Buffer.from(bytes))) await once2(this.stream, "drain");
       return;
     }
-    this.buffered.push(bytes);
+    this.buffered.push(new Uint8Array(bytes));
     this.bufferedLen += bytes.length;
     if (this.bufferedLen > this.threshold) this.startResumable();
   }
@@ -744,7 +812,7 @@ var GcsUploadSink = class _GcsUploadSink {
         }
         if (!isThrottle(err)) throw err;
         if (resent >= THROTTLE_RESENDS) {
-          throw new TransientError(
+          throw new TransientError2(
             `GCS upload was throttled on each of its ${resent + 1} sends; the object may or may not exist`,
             { cause: err }
           );
@@ -773,11 +841,32 @@ 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";
+
+// src/crc32c.ts
+var TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 2197175160 ^ c >>> 1 : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+function crc32cBase64(bytes) {
+  let crc = 4294967295;
+  for (const byte of bytes) crc = TABLE[(crc ^ byte) & 255] ^ crc >>> 8;
+  const value = (crc ^ 4294967295) >>> 0;
+  const out = Buffer.alloc(4);
+  out.writeUInt32BE(value);
+  return out.toString("base64");
+}
+
+// src/registry.ts
 var GcsRegistryStore = class {
   constructor(storage, readStorage, bucket, readTimeoutMs, conditionalDelete) {
     this.storage = storage;
@@ -785,6 +874,7 @@ var GcsRegistryStore = class {
     this.bucket = bucket;
     this.readTimeoutMs = readTimeoutMs;
     this.conditionalDelete = conditionalDelete;
+    this.presence = new BucketPresence(storage, bucket);
   }
   storage;
   readStorage;
@@ -792,6 +882,7 @@ var GcsRegistryStore = class {
   readTimeoutMs;
   conditionalDelete;
   label = "GCS";
+  presence;
   /** A handle on one registry object. */
   file(name) {
     return this.storage.bucket(this.bucket).file(name);
@@ -817,7 +908,10 @@ var GcsRegistryStore = class {
         deadline
       );
     } catch (err) {
-      if (isNotFound(err)) return null;
+      if (isNotFound(err)) {
+        await this.presence.confirm();
+        return null;
+      }
       throw mapReadError(err);
     }
     if (res.status !== 200) {
@@ -833,6 +927,11 @@ var GcsRegistryStore = class {
     try {
       await saveOnce(this.file(key), body, {
         contentType: "application/json",
+        // The checksum goes with the upload, for GCS to check before it stores anything. The SDK's own check runs
+        // after the upload instead, and on a mismatch, or an answer that names no checksum, deletes the object by
+        // name with no precondition: for a row, that is the live row, another writer's newer one included.
+        validation: false,
+        metadata: { crc32c: crc32cBase64(body) },
         preconditionOpts: {
           ifGenerationMatch: expect === "absent" ? 0 : generationFence(expect.version, key)
         }
@@ -849,6 +948,7 @@ var GcsRegistryStore = class {
       await this.file(key).delete({ ifGenerationMatch: generationFence(expect.version, key) });
     } catch (err) {
       if (isPreconditionFailed(err) || isNotFound(err)) {
+        if (isNotFound(err)) await this.presence.confirm();
         throw new WriteConflictError2(`registry OCC conflict deleting ${key}`);
       }
       throw mapError(err);
@@ -865,6 +965,9 @@ var GcsRegistryStore = class {
         throw mapError(err);
       }
       for (const f of files ?? []) yield f.name;
+      if (next?.pageToken !== void 0 && next.pageToken === pageToken) {
+        throw new IntegrityError("GCS listing returned the page token it was given");
+      }
       pageToken = next?.pageToken;
     } while (pageToken !== void 0);
   }
@@ -878,9 +981,9 @@ function generationFence(version, key) {
 }
 function mapReadError(err) {
   err = scrubCredentials(err);
-  if (err instanceof ReadTimedOut) return new TransientError2(err.message, { cause: err });
+  if (err instanceof ReadTimedOut) return new TransientError3(err.message, { cause: err });
   if (isTransportFault(err)) {
-    return new TransientError2(`transient GCS fault: ${String(err.code)}`, {
+    return new TransientError3(`transient GCS fault: ${String(err.code)}`, {
       cause: err
     });
   }
@@ -889,7 +992,7 @@ function mapReadError(err) {
 function mapError(err) {
   err = scrubCredentials(err);
   if (isTransient(err)) {
-    return new TransientError2(
+    return new TransientError3(
       `transient GCS fault: ${err?.code ?? err?.name ?? "unknown"}`,
       { cause: err }
     );
@@ -921,6 +1024,115 @@ var GcsRegistryDriver = class extends ObjectStoreRegistry {
   }
 };
 
+// src/read-client.ts
+import { ValidationError as ValidationError5 } from "@cloudbitmaps/core/driver-kit";
+function downloadClient(client, supplied) {
+  if (!isSdkClient(client)) {
+    if (client.retryOptions?.autoRetry === false) return client;
+    throw supplied ? refusal(
+      true,
+      "it is not a `Storage` client (a test double, say)",
+      "Give it `retryOptions: { autoRetry: false }` to have it used as it is"
+    ) : refusal(
+      false,
+      "the `Storage` it was built from is not the SDK's (a mocked module, say)",
+      "Pass the mock as `client`, with `retryOptions: { autoRetry: false }`"
+    );
+  }
+  const instead = "Stub `Storage.prototype.bucket` instead, which reaches that client too, or pass a test double that does not extend `Storage`, with `retryOptions: { autoRetry: false }`";
+  if (Object.hasOwn(client, "bucket")) {
+    throw refusal(
+      supplied,
+      "its `bucket` method is replaced on the instance, as by a test stub, which a client built from its class would not have",
+      instead
+    );
+  }
+  if (overridesBucket(client)) {
+    throw refusal(
+      supplied,
+      "its class overrides `bucket`, as a test double built on `Storage` does, so a client built from its class need not hold what this one holds",
+      instead
+    );
+  }
+  const second = supplied ? "a second client built from its class with its settings" : "a second client built from the same settings";
+  const remedy = supplied ? "Pass a client its class builds from the options it is given, as `Storage` does, or leave out `client`" : void 0;
+  let twin;
+  try {
+    twin = twinOf(client);
+  } catch (err) {
+    throw refusal(supplied, `${second} could not be built`, remedy, err);
+  }
+  const why = unfaithful(client, twin);
+  if (why !== void 0) throw refusal(supplied, `${second} ${why}`, remedy);
+  return twin;
+}
+function isSdkClient(client) {
+  const factory = client.makeAuthenticatedRequest;
+  return client.authClient !== void 0 && typeof factory === "function" && factory.authClient === client.authClient;
+}
+function overridesBucket(client) {
+  let defined = 0;
+  for (let proto = Object.getPrototypeOf(client); proto !== null; ) {
+    if (Object.hasOwn(proto, "bucket")) defined++;
+    proto = Object.getPrototypeOf(proto);
+  }
+  return defined > 1;
+}
+function twinOf(client) {
+  const Own = client.constructor;
+  const twin = new Own({
+    authClient: client.authClient,
+    // The SDK treats an endpoint spelled other than its default as a custom one, whose requests go without credentials,
+    // and then stores it with any trailing slash taken off. A client given the default in another spelling is custom
+    // with the default's URL, which that URL with a slash reproduces.
+    apiEndpoint: client.customEndpoint === true ? `${client.apiEndpoint}/` : client.apiEndpoint,
+    universeDomain: client.universeDomain,
+    projectId: client.projectId,
+    ...client.useAuthWithCustomEndpoint === void 0 ? {} : { useAuthWithCustomEndpoint: client.useAuthWithCustomEndpoint },
+    ...client.providedUserAgent === void 0 ? {} : { userAgent: client.providedUserAgent },
+    ...client.timeout === void 0 ? {} : { timeout: client.timeout },
+    crc32cGenerator: client.crc32cGenerator,
+    retryOptions: { ...client.retryOptions, autoRetry: false },
+    // A view, not a copy: the client's interceptors as they are when each request is sent.
+    interceptors_: [
+      {
+        request: (options) => client.getRequestInterceptors().reduce(
+          (sent, intercept) => intercept(sent),
+          options
+        )
+      }
+    ]
+  });
+  if (twin !== client && twin.retryOptions !== void 0 && twin.retryOptions !== client.retryOptions) {
+    twin.retryOptions.autoRetry = false;
+  }
+  return twin;
+}
+function unfaithful(client, twin) {
+  if (twin === client) return "is the same client";
+  if (typeof twin.bucket !== "function") return "has no `bucket` method";
+  if (twin.authClient === void 0 || twin.authClient !== client.authClient) {
+    return "would use other credentials";
+  }
+  if (twin.retryOptions === client.retryOptions) return "would share its retry settings";
+  if (twin.retryOptions?.autoRetry !== false) return "keeps the SDK's retries";
+  if (twin.baseUrl !== client.baseUrl) {
+    return "would send to another URL, as when `STORAGE_EMULATOR_HOST` changed after the client was built or is not a URL";
+  }
+  if (twin.apiEndpoint !== client.apiEndpoint) return "would name another endpoint";
+  if (twin.customEndpoint !== client.customEndpoint) {
+    return "would decide otherwise whether requests carry credentials";
+  }
+  return void 0;
+}
+function refusal(supplied, why, remedy, cause) {
+  const err = new ValidationError5(
+    (supplied ? `GcsStorage cannot send the supplied client's downloads without the SDK's retries: ${why}` : `GcsStorage cannot build a client that sends downloads without the SDK's retries: ${why}`) + (remedy === void 0 ? "" : `. ${remedy}`)
+  );
+  if (cause !== void 0) err.cause = scrubCredentials(cause);
+  return err;
+}
+
 // src/backend.ts
 var GCS_STORAGE_OPTION_KEYS = [
   "bucket",
@@ -937,14 +1149,14 @@ var GCS_STORAGE_OPTION_KEYS = [
 var CLIENT_SETTINGS = ["projectId", "apiEndpoint"];
 function refuseUnknown(name, options, keys, hint) {
   if (options === null || typeof options !== "object") {
-    throw new ValidationError5(
+    throw new ValidationError6(
       `${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(
+    throw new ValidationError6(
       `${name} does not take ${list(unknown)}. It takes ${list(keys)}; ${hint}.`
     );
   }
@@ -962,22 +1174,30 @@ var GcsStorage = class {
       GCS_STORAGE_OPTION_KEYS,
       "a @google-cloud/storage client goes in `client`"
     );
+    if (typeof options.bucket !== "string" || options.bucket.length === 0) {
+      throw new ValidationError6("GcsStorage needs a `bucket`: the name of one, a non-empty string");
+    }
+    if (options.now !== void 0 && typeof options.now !== "function") {
+      throw new ValidationError6(
+        "GcsStorage's `now` must be a function that returns epoch milliseconds"
+      );
+    }
     if (options.client !== void 0 && options.client !== null) {
       const ignored = CLIENT_SETTINGS.filter((k) => options[k] !== void 0);
       if (ignored.length > 0) {
-        throw new ValidationError5(
+        throw new ValidationError6(
           `GcsStorage 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\``
         );
       }
       this.client = options.client;
-      readClient = options.client;
+      readClient = downloadClient(options.client, true);
     } else {
       const settings = {
         ...options.projectId === void 0 ? {} : { projectId: options.projectId },
         ...options.apiEndpoint === void 0 ? {} : { apiEndpoint: options.apiEndpoint }
       };
       this.client = new GcsClient(settings);
-      readClient = new GcsClient({ ...settings, retryOptions: { autoRetry: false } });
+      readClient = downloadClient(this.client, false);
     }
     const shared = {
       storage: this.client,