@cloudbitmaps/gcs 0.11.1 → 0.12.0

package/dist/index.js

@@ -1,12 +1,12 @@
 // src/backend.ts
-import { ValidationError as ValidationError3, brandAsBackend } from "@cloudbitmaps/core/driver-kit";
+import { ValidationError as ValidationError5, brandAsBackend } from "@cloudbitmaps/core/driver-kit";
 import { Storage as GcsClient } from "@google-cloud/storage";
 
 // src/storage.ts
 import {
   NotFoundError,
   TransientError,
-  ValidationError as ValidationError2,
+  ValidationError as ValidationError3,
   WriteConflictError,
   isNotFoundError,
   isValidationError,
@@ -72,20 +72,145 @@ function networkCode(err) {
 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;
 }
 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";
+}
+var TRANSPORT_CODES = /* @__PURE__ */ new Set([
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ECONNABORTED",
+  "ETIMEDOUT",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "EPIPE",
+  "ERR_STREAM_PREMATURE_CLOSE"
+]);
+function isTransportFault(err) {
+  if (httpStatus(err) !== void 0) return false;
+  const code = networkCode(err);
+  return code !== void 0 && TRANSPORT_CODES.has(code);
+}
+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 === 429 || status !== void 0 && status >= 500 && status < 600) return true;
+  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";
 }
 
+// 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;
+var MAX_DELAY_MS = 1e3;
+var MIN_RETRY_MS = 10;
+async function retryDownload(download, deadline) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await download();
+    } catch (err) {
+      if (err instanceof ReadTimedOut) throw err;
+      if (attempt >= RETRIES || !isDownloadRetryable(err)) throw err;
+      const left = deadline?.remaining() ?? Infinity;
+      if (deadline !== void 0 && left < MIN_RETRY_MS) throw deadline.expired(err);
+      const ceiling = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** attempt);
+      const delay = Math.random() * ceiling;
+      await new Promise((resolve) => setTimeout(resolve, Math.min(delay, left)));
+      if (deadline !== void 0 && deadline.remaining() < MIN_RETRY_MS)
+        throw deadline.expired(err);
+    }
+  }
+}
+
 // src/send-once.ts
 import { once } from "node:events";
 async function saveOnce(file, body, options) {
@@ -95,18 +220,96 @@ async function saveOnce(file, body, options) {
   await stored;
 }
 
+// src/read-once.ts
+var OFF_THE_SHARED_AGENT = {
+  request: (reqOpts) => ({ ...reqOpts, forever: false })
+};
+function downloadFile(storage, bucket, name) {
+  const file = storage.bucket(bucket).file(name);
+  file.interceptors.push(OFF_THE_SHARED_AGENT);
+  return file;
+}
+function singleHeader(headers, name) {
+  const value = headers[name];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function readOnce(file, options, maxBytes, oversize, deadline) {
+  if (deadline !== void 0 && deadline.remaining() === 0)
+    return Promise.reject(deadline.expired());
+  return new Promise((resolve, reject) => {
+    const stream = file.createReadStream(options);
+    const chunks = [];
+    let total = 0;
+    let status = 0;
+    let headers = {};
+    let responded = false;
+    let settled = false;
+    const timer = deadline === void 0 ? void 0 : setTimeout(() => fail(deadline.expired()), deadline.remaining());
+    const release = () => void setImmediate(() => stream.destroy());
+    const fail = (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (responded) release();
+      reject(err);
+    };
+    stream.on("response", (res) => {
+      responded = true;
+      if (settled) return release();
+      status = typeof res.statusCode === "number" ? res.statusCode : 0;
+      headers = res.headers ?? {};
+      if (status < 200 || status > 299) return;
+      const advertised = singleHeader(headers, "content-length");
+      if (advertised !== void 0 && /^\d+$/.test(advertised) && Number(advertised) > maxBytes) {
+        fail(oversize(Number(advertised)));
+      }
+    });
+    stream.on("data", (chunk) => {
+      if (settled) return;
+      total += chunk.length;
+      if (total > maxBytes) return fail(oversize(void 0));
+      chunks.push(chunk);
+    });
+    stream.on("error", fail);
+    stream.on("end", () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ status, headers, bytes: new Uint8Array(Buffer.concat(chunks, total)) });
+    });
+    stream.on(
+      "close",
+      () => fail(
+        Object.assign(new Error("GCS read ended before the response completed"), {
+          code: "ECONNRESET"
+        })
+      )
+    );
+  });
+}
+
 // src/storage.ts
 var DEFAULT_MAX_OBJECT_BYTES = 5 * 1024 * 1024 * 1024 * 1024;
 var WRITE_ID_KEY = "cbwid";
+var THROTTLE_RESENDS = 3;
+var THROTTLE_BASE_DELAY_MS = 500;
+var REAL_TIME = {
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+};
 var DEFAULT_UPLOAD_THRESHOLD_BYTES = 8 * 1024 * 1024;
 var GcsStorageDriver = class {
   storage;
+  readStorage;
   bucket;
   prefix;
   maxObjectBytes;
   threshold;
+  readTimeoutMs;
+  clock;
   constructor(options) {
     this.storage = options.storage;
+    this.clock = options.clock ?? REAL_TIME;
+    this.readStorage = options.readStorage ?? options.storage;
     this.bucket = options.bucket;
     this.prefix = normalizeGcsPrefix(options.prefix);
     for (const [name, value] of [
@@ -114,11 +317,12 @@ var GcsStorageDriver = class {
       ["simpleUploadThresholdBytes", options.simpleUploadThresholdBytes]
     ]) {
       if (value !== void 0 && (!Number.isSafeInteger(value) || value < 1)) {
-        throw new ValidationError2(`${name} must be a positive safe integer; got ${value}`);
+        throw new ValidationError3(`${name} must be a positive safe integer; got ${value}`);
       }
     }
     this.maxObjectBytes = options.maxObjectBytes ?? DEFAULT_MAX_OBJECT_BYTES;
     this.threshold = options.simpleUploadThresholdBytes ?? DEFAULT_UPLOAD_THRESHOLD_BYTES;
+    this.readTimeoutMs = resolveReadTimeoutMs(options.readTimeoutMs);
   }
   capabilities() {
     return { rangeRead: true, maxObjectBytes: this.maxObjectBytes, conditionalPut: true };
@@ -126,9 +330,22 @@ var GcsStorageDriver = class {
   file(name) {
     return this.storage.bucket(this.bucket).file(name);
   }
+  /** The same object on the download client, off the SDK's shared agent ({@link downloadFile}). */
+  downloadable(name) {
+    return downloadFile(this.readStorage, this.bucket, name);
+  }
+  /** The deadline a read of `key` made now runs under, every attempt included, named for its error; none when off. */
+  deadline(read, key) {
+    return startDeadline(this.readTimeoutMs, `${read} of ${key.segment}.${key.generation}`);
+  }
   async putImmutable(key, write) {
     const objectName = storageObjectName(this.prefix, key);
-    const sink = new GcsUploadSink(this.file(objectName), this.maxObjectBytes, this.threshold);
+    const sink = new GcsUploadSink(
+      this.file(objectName),
+      this.maxObjectBytes,
+      this.threshold,
+      this.clock
+    );
     try {
       await write(sink);
       return await sink.finish();
@@ -145,41 +362,150 @@ var GcsStorageDriver = class {
   }
   async getRange(key, offset, length) {
     if (!Number.isInteger(offset) || !Number.isInteger(length) || offset < 0 || length < 0) {
-      throw new ValidationError2(`invalid range offset=${offset} length=${length}`);
+      throw new ValidationError3(`invalid range offset=${offset} length=${length}`);
     }
     if (length === 0) return new Uint8Array(0);
     const objectName = storageObjectName(this.prefix, key);
     try {
-      const [buf] = await this.file(objectName).download({
-        start: offset,
-        end: offset + length - 1
-      });
-      if (buf.length !== length) {
-        throw new ValidationError2(
-          `range [${offset}, ${offset + length}) out of bounds (got ${buf.length}B)`
-        );
-      }
-      return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+      const deadline = this.deadline("range read", key);
+      const res = await retryDownload(
+        () => readOnce(
+          this.downloadable(objectName),
+          { start: offset, end: offset + length - 1, decompress: false },
+          length,
+          () => this.badRange(key, `the response is longer than the ${length}B requested`),
+          deadline
+        ),
+        deadline
+      );
+      this.checkRange(res, key, offset, length);
+      return res.bytes;
     } catch (err) {
       throw this.mapReadError(err, key);
     }
   }
+  /**
+   * Refuse a range response unless it is exactly the bytes asked for. A 206 must name them in `Content-Range: bytes
+   * a-b/total`, starting at `offset`, and hold that many; a 200 (a server that ignored the range) is the whole object,
+   * which is the range only when the range starts at 0. A short read means the range ran past the end of the object:
+   * out of bounds, never a partial result.
+   */
+  checkRange(res, key, offset, length) {
+    const received = res.bytes.length;
+    if (res.status === 200) {
+      if (offset !== 0)
+        throw this.badRange(key, `whole object returned for a range from ${offset}`);
+    } else if (res.status === 206) {
+      const header = singleHeader(res.headers, "content-range");
+      const m = header === void 0 ? null : /^bytes (\d+)-(\d+)\/(\d+)$/.exec(header);
+      if (m === null) throw this.badRange(key, "Content-Range is missing or malformed");
+      const [first, last, total] = [Number(m[1]), Number(m[2]), Number(m[3])];
+      if (![first, last, total].every(Number.isSafeInteger)) {
+        throw this.badRange(key, "Content-Range holds a number that is not a safe integer");
+      }
+      if (first !== offset || last - first + 1 !== received || last >= total) {
+        throw this.badRange(
+          key,
+          `Content-Range ${first}-${last}/${total} disagrees with ${received}B received from ${offset}`
+        );
+      }
+    } else {
+      throw this.badRange(key, `unexpected HTTP ${res.status}`);
+    }
+    if (received !== length) {
+      throw new ValidationError3(
+        `range [${offset}, ${offset + length}) out of bounds (got ${received}B)`
+      );
+    }
+  }
+  badRange(key, why) {
+    return new ValidationError3(
+      `GCS range read of ${key.segment}.${key.generation} refused: ${why}`
+    );
+  }
   async getTail(key, maxBytes) {
     const objectName = storageObjectName(this.prefix, key);
+    const deadline = this.deadline("tail read", key);
     try {
-      const [meta] = await this.file(objectName).getMetadata();
-      const size = Number(meta.size ?? 0);
-      if (!Number.isSafeInteger(size) || size < 0) {
-        throw new ValidationError2(`GCS returned an invalid object size: ${String(meta.size)}`);
+      if (maxBytes <= 0)
+        return { bytes: new Uint8Array(0), size: await this.sizeOf(objectName, deadline) };
+      if (!Number.isSafeInteger(maxBytes)) {
+        throw new ValidationError3(`invalid tail length ${maxBytes}`);
+      }
+      let res;
+      try {
+        res = await retryDownload(
+          () => readOnce(
+            this.downloadable(objectName),
+            { end: -maxBytes, decompress: false },
+            maxBytes,
+            () => this.badTail(key, `the response is longer than the ${maxBytes}B requested`),
+            deadline
+          ),
+          deadline
+        );
+      } catch (err) {
+        if (!isInvalidRange(err)) throw err;
+        const size = await this.sizeOf(objectName, deadline);
+        if (size !== 0) throw err;
+        return { bytes: new Uint8Array(0), size };
+      }
+      if (res.bytes.length === 0) {
+        const size = await this.sizeOf(objectName, deadline);
+        if (size !== 0) throw this.badTail(key, `no bytes returned for an object of ${size}B`);
+        return { bytes: res.bytes, size };
       }
-      if (maxBytes <= 0 || size === 0) return { bytes: new Uint8Array(0), size };
-      const start = Math.max(0, size - maxBytes);
-      const [buf] = await this.file(objectName).download({ start, end: size - 1 });
-      return { bytes: new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength), size };
+      return { bytes: res.bytes, size: this.tailSize(res, maxBytes, key) };
     } catch (err) {
       throw this.mapReadError(err, key);
     }
   }
+  /**
+   * The object's size from its metadata, validated. Read on the download client and retried as a download is, within
+   * the calling read's `deadline` ({@link withDeadline}), so nothing but the one request in flight runs past it.
+   */
+  async sizeOf(objectName, deadline) {
+    const [meta] = await retryDownload(
+      () => withDeadline(() => this.downloadable(objectName).getMetadata(), deadline),
+      deadline
+    );
+    const size = Number(meta.size ?? 0);
+    if (!Number.isSafeInteger(size) || size < 0) {
+      throw new ValidationError3(`GCS returned an invalid object size: ${String(meta.size)}`);
+    }
+    return size;
+  }
+  /**
+   * The object's total size from a tail response, refused unless every header agrees with the bytes received. A 206
+   * must carry `Content-Range: bytes a-b/total` that names exactly the suffix asked for and exactly the bytes held;
+   * a 200 (a server that ignored the range) is the whole object, and is accepted only when it fits in the request.
+   */
+  tailSize(res, maxBytes, key) {
+    const received = res.bytes.length;
+    if (res.status === 200) {
+      if (received > maxBytes)
+        throw this.badTail(key, "whole object returned past the requested length");
+      return received;
+    }
+    if (res.status !== 206) throw this.badTail(key, `unexpected HTTP ${res.status}`);
+    const header = singleHeader(res.headers, "content-range");
+    const m = header === void 0 ? null : /^bytes (\d+)-(\d+)\/(\d+)$/.exec(header);
+    if (m === null) throw this.badTail(key, `Content-Range is missing or malformed`);
+    const [first, last, total] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    if (![first, last, total].every(Number.isSafeInteger)) {
+      throw this.badTail(key, "Content-Range holds a number that is not a safe integer");
+    }
+    if (last !== total - 1 || first !== Math.max(0, total - maxBytes) || last - first + 1 !== received) {
+      throw this.badTail(
+        key,
+        `Content-Range ${first}-${last}/${total} disagrees with ${received}B received for a ${maxBytes}B tail`
+      );
+    }
+    return total;
+  }
+  badTail(key, why) {
+    return new ValidationError3(`GCS tail read of ${key.segment}.${key.generation} refused: ${why}`);
+  }
   async delete(key) {
     try {
       await this.file(storageObjectName(this.prefix, key)).delete({ ignoreNotFound: true });
@@ -208,15 +534,24 @@ var GcsStorageDriver = class {
     if (isNotFound(err))
       return new NotFoundError(`no such generation: ${key.segment}.${key.generation}`);
     if (isInvalidRange(err)) {
-      return new ValidationError2(`range out of bounds for ${key.segment}.${key.generation}`);
+      return new ValidationError3(`range out of bounds for ${key.segment}.${key.generation}`);
+    }
+    if (err instanceof ReadTimedOut) return new TransientError(err.message, { cause: err });
+    if (isTransportFault(err)) {
+      return new TransientError(
+        `transient GCS fault: ${String(err.code)}`,
+        {
+          cause: err
+        }
+      );
     }
     return this.mapError(err);
   }
   /**
    * Reclassify a transient GCS 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-call site, so callers and the read
-   * retry only ever see typed errors.
+   * everything else propagates unchanged. The final fallback at every client-call site: an HTTP status and a fault
+   * in transit arrive typed, and anything else (a checksum mismatch, a credentials failure) as the SDK raised it.
    */
   mapError(err) {
     if (isTransient(err)) {
@@ -238,14 +573,16 @@ function concatBytes(parts, total) {
   return out;
 }
 var GcsUploadSink = class _GcsUploadSink {
-  constructor(file, maxObjectBytes, threshold) {
+  constructor(file, maxObjectBytes, threshold, clock) {
     this.file = file;
     this.maxObjectBytes = maxObjectBytes;
     this.threshold = threshold;
+    this.clock = clock;
   }
   file;
   maxObjectBytes;
   threshold;
+  clock;
   hash = createHash("sha256");
   total = 0;
   buffered = [];
@@ -260,16 +597,26 @@ var GcsUploadSink = class _GcsUploadSink {
     metadata: { contentType: "application/octet-stream" }
   };
   /**
-   * This write's own id, which the resumable upload stores in the object's custom metadata (outside the `.crbm`
-   * bytes) so a conflict can be told from a replay of this same write. The simple upload is sent once and needs none.
+   * This write's own id, stored in the object's custom metadata (outside the `.crbm` bytes) so a conflict can be told
+   * from a replay of this same write: the resumable session's, or the simple upload's re-send after a throttle.
    */
   writeId = randomBytes(16).toString("hex");
+  /** The upload options with this write's id in the object's custom metadata. */
+  tagged() {
+    return {
+      ..._GcsUploadSink.WRITE_OPTS,
+      metadata: {
+        ..._GcsUploadSink.WRITE_OPTS.metadata,
+        metadata: { [WRITE_ID_KEY]: this.writeId }
+      }
+    };
+  }
   async write(bytes) {
     if (this.failure !== void 0) throw this.failure;
     if (bytes.length === 0) return;
     this.total += bytes.length;
     if (this.total > this.maxObjectBytes) {
-      throw new ValidationError2(`object exceeds maxObjectBytes ${this.maxObjectBytes}`);
+      throw new ValidationError3(`object exceeds maxObjectBytes ${this.maxObjectBytes}`);
     }
     this.hash.update(bytes);
     if (this.stream !== void 0) {
@@ -282,14 +629,7 @@ var GcsUploadSink = class _GcsUploadSink {
   }
   /** Cross into resumable streaming: open the stream, flush the buffered bytes, keep only ~one threshold resident. */
   startResumable() {
-    const stream = this.file.createWriteStream({
-      resumable: true,
-      ..._GcsUploadSink.WRITE_OPTS,
-      metadata: {
-        ..._GcsUploadSink.WRITE_OPTS.metadata,
-        metadata: { [WRITE_ID_KEY]: this.writeId }
-      }
-    });
+    const stream = this.file.createWriteStream({ resumable: true, ...this.tagged() });
     this.stream = stream;
     this.done = once2(stream, "finish");
     stream.on("error", (e) => {
@@ -304,11 +644,7 @@ var GcsUploadSink = class _GcsUploadSink {
   async finish() {
     const sha256 = this.hash.digest("hex");
     if (this.stream === void 0) {
-      await saveOnce(
-        this.file,
-        concatBytes(this.buffered, this.bufferedLen),
-        _GcsUploadSink.WRITE_OPTS
-      );
+      await this.sendSimple(concatBytes(this.buffered, this.bufferedLen));
       return { size: this.total, sha256 };
     }
     try {
@@ -320,6 +656,34 @@ var GcsUploadSink = class _GcsUploadSink {
     }
     return { size: this.total, sha256 };
   }
+  /**
+   * Send the simple upload once, and again after a `429` or `503`, up to {@link THROTTLE_RESENDS} times, waiting a
+   * full-jitter backoff before each. Any other failure is thrown at once. Once it has been sent again, a `412` can be
+   * an earlier send that landed after all, so the object's write id decides: this write's own is a success, and any
+   * other object, or one with no id, is the conflict. A failed read-back throws, and is neither. Exhausted, it throws
+   * {@link TransientError}; nothing is deleted.
+   */
+  async sendSimple(body) {
+    for (let resent = 0; ; resent++) {
+      try {
+        await saveOnce(this.file, body, this.tagged());
+        return;
+      } catch (err) {
+        if (resent > 0 && isPreconditionFailed(err)) {
+          if (await this.storedWriteId() === this.writeId) return;
+          throw err;
+        }
+        if (!isThrottle(err)) throw err;
+        if (resent >= THROTTLE_RESENDS) {
+          throw new TransientError(
+            `GCS upload was throttled on each of its ${resent + 1} sends; the object may or may not exist`,
+            { cause: err }
+          );
+        }
+        await this.clock.sleep(Math.floor(Math.random() * THROTTLE_BASE_DELAY_MS * 2 ** resent));
+      }
+    }
+  }
   /** The id the stored object carries in its custom metadata, or `undefined` when it carries none or is gone. */
   async storedWriteId() {
     try {
@@ -340,44 +704,61 @@ import {
   IntegrityError,
   MAX_ROW_BYTES,
   ObjectStoreRegistry,
-  ObjectVersionRaced,
   TransientError as TransientError2,
+  ValidationError as ValidationError4,
   WriteConflictError as WriteConflictError2,
   normalizeObjectPrefix
 } from "@cloudbitmaps/core/driver-kit";
-var GcsStore = class {
-  constructor(storage, bucket) {
+var GcsRegistryStore = class {
+  constructor(storage, readStorage, bucket, readTimeoutMs, conditionalDelete) {
     this.storage = storage;
+    this.readStorage = readStorage;
     this.bucket = bucket;
+    this.readTimeoutMs = readTimeoutMs;
+    this.conditionalDelete = conditionalDelete;
   }
   storage;
+  readStorage;
   bucket;
+  readTimeoutMs;
+  conditionalDelete;
   label = "GCS";
-  /** A file handle, optionally pinned to one object generation (GCS's version fence). */
-  file(name, generation) {
-    return generation === void 0 ? this.storage.bucket(this.bucket).file(name) : this.storage.bucket(this.bucket).file(name, { generation });
+  /** A handle on one registry object. */
+  file(name) {
+    return this.storage.bucket(this.bucket).file(name);
+  }
+  /** The same file handle on the download client, off the SDK's shared agent ({@link downloadFile}). */
+  downloadable(name) {
+    return downloadFile(this.readStorage, this.bucket, name);
   }
   async read(key) {
-    let generation;
-    let size;
+    let res;
     try {
-      const [meta] = await this.file(key).getMetadata();
-      generation = String(meta.generation ?? "");
-      size = Number(meta.size ?? 0);
+      const deadline = startDeadline(this.readTimeoutMs, `registry read of ${key}`);
+      res = await retryDownload(
+        () => readOnce(
+          this.downloadable(key),
+          {},
+          MAX_ROW_BYTES,
+          (size) => new IntegrityError(
+            size === void 0 ? `registry object exceeds cap ${MAX_ROW_BYTES}B` : `registry object ${size}B exceeds cap ${MAX_ROW_BYTES}B`
+          ),
+          deadline
+        ),
+        deadline
+      );
     } catch (err) {
       if (isNotFound(err)) return null;
-      throw mapError(err);
+      throw mapReadError(err);
     }
-    if (size > MAX_ROW_BYTES) {
-      throw new IntegrityError(`registry object ${size}B exceeds cap ${MAX_ROW_BYTES}B`);
+    if (res.status !== 200) {
+      throw new IntegrityError(`registry read answered HTTP ${res.status}, not 200: ${key}`);
     }
-    try {
-      const [buf] = await this.file(key, generation).download();
-      return { bytes: new Uint8Array(buf), version: generation };
-    } catch (err) {
-      if (isNotFound(err)) throw new ObjectVersionRaced(key);
-      throw mapError(err);
+    const generation = singleHeader(res.headers, "x-goog-generation");
+    if (generation === void 0 || !/^[1-9]\d*$/.test(generation) || !Number.isSafeInteger(Number(generation))) {
+      throw new IntegrityError(`registry read carries no usable x-goog-generation: ${key}`);
     }
+    return { bytes: res.bytes, version: generation };
   }
   async write(key, body, expect) {
     try {
@@ -394,6 +775,16 @@ var GcsStore = class {
       throw mapError(err);
     }
   }
+  async delete(key, expect) {
+    try {
+      await this.file(key).delete({ ifGenerationMatch: generationFence(expect.version, key) });
+    } catch (err) {
+      if (isPreconditionFailed(err) || isNotFound(err)) {
+        throw new WriteConflictError2(`registry OCC conflict deleting ${key}`);
+      }
+      throw mapError(err);
+    }
+  }
   async *listKeys(prefix) {
     let pageToken;
     do {
@@ -416,19 +807,43 @@ function generationFence(version, key) {
   }
   return generation;
 }
+function mapReadError(err) {
+  if (err instanceof ReadTimedOut) return new TransientError2(err.message, { cause: err });
+  if (isTransportFault(err)) {
+    return new TransientError2(`transient GCS fault: ${String(err.code)}`, {
+      cause: err
+    });
+  }
+  return mapError(err);
+}
 function mapError(err) {
   if (isTransient(err)) {
     return new TransientError2(
-      `transient GCS fault: ${err?.name ?? "unknown"}`,
+      `transient GCS fault: ${err?.code ?? err?.name ?? "unknown"}`,
       { cause: err }
     );
   }
   return err;
 }
+function resolveConditionalDelete(value) {
+  if (value === void 0) {
+    return false;
+  }
+  if (typeof value !== "boolean") {
+    throw new ValidationError4(`conditionalDelete must be a boolean; got ${String(value)}`);
+  }
+  return value;
+}
 var GcsRegistryDriver = class extends ObjectStoreRegistry {
   constructor(options) {
     super(
-      new GcsStore(options.storage, options.bucket),
+      new GcsRegistryStore(
+        options.storage,
+        options.readStorage ?? options.storage,
+        options.bucket,
+        resolveReadTimeoutMs(options.readTimeoutMs),
+        resolveConditionalDelete(options.conditionalDelete)
+      ),
       normalizeObjectPrefix(options.prefix),
       options.now ?? (() => Date.now())
     );
@@ -444,19 +859,21 @@ var GCS_STORAGE_OPTION_KEYS = [
   "apiEndpoint",
   "maxObjectBytes",
   "simpleUploadThresholdBytes",
-  "now"
+  "now",
+  "readTimeoutMs",
+  "conditionalDelete"
 ];
 var CLIENT_SETTINGS = ["projectId", "apiEndpoint"];
 function refuseUnknown(name, options, keys, hint) {
   if (options === null || typeof options !== "object") {
-    throw new ValidationError3(
+    throw new ValidationError5(
       `${name} needs an options object \u2014 got ${options === null ? "null" : typeof options}`
     );
   }
   const unknown = Object.keys(options).filter((k) => !keys.includes(k));
   if (unknown.length > 0) {
     const list = (ks) => ks.map((k) => `\`${k}\``).join(", ");
-    throw new ValidationError3(
+    throw new ValidationError5(
       `${name} does not take ${list(unknown)}. It takes ${list(keys)}; ${hint}.`
     );
   }
@@ -467,6 +884,7 @@ var GcsStorage = class {
   /** The client both halves share — built here unless one was supplied. */
   client;
   constructor(options) {
+    let readClient;
     refuseUnknown(
       "GcsStorage",
       options,
@@ -476,21 +894,26 @@ var GcsStorage = class {
     if (options.client !== void 0 && options.client !== null) {
       const ignored = CLIENT_SETTINGS.filter((k) => options[k] !== void 0);
       if (ignored.length > 0) {
-        throw new ValidationError3(
+        throw new ValidationError5(
           `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;
     } else {
-      this.client = new GcsClient({
+      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 } });
     }
     const shared = {
       storage: this.client,
+      readStorage: readClient,
       bucket: options.bucket,
-      ...options.prefix === void 0 ? {} : { prefix: options.prefix }
+      ...options.prefix === void 0 ? {} : { prefix: options.prefix },
+      ...options.readTimeoutMs === void 0 ? {} : { readTimeoutMs: options.readTimeoutMs }
     };
     this.storage = new GcsStorageDriver({
       ...shared,
@@ -499,7 +922,8 @@ var GcsStorage = class {
     });
     this.registry = new GcsRegistryDriver({
       ...shared,
-      ...options.now === void 0 ? {} : { now: options.now }
+      ...options.now === void 0 ? {} : { now: options.now },
+      ...options.conditionalDelete === void 0 ? {} : { conditionalDelete: options.conditionalDelete }
     });
     brandAsBackend(this);
   }