@cloudbitmaps/core 0.1.0-rc.0

package/dist/gcs/index.js

@@ -0,0 +1,279 @@
+import { WriteConflictError, isValidationError, isWriteConflictError, isNotFoundError, ValidationError, NotFoundError, TransientError, validateSegmentRef, namespacePart } from '../chunk-NUIDEEFZ.js';
+import { createHash } from 'crypto';
+import { once } from 'events';
+
+// src/drivers/gcs/keys.ts
+var SUFFIX = ".crbm";
+function prefixPart(prefix) {
+  if (prefix === void 0) return "";
+  const trimmed = prefix.replace(/^\/+|\/+$/g, "");
+  return trimmed === "" ? "" : `${trimmed}/`;
+}
+function normalizeGcsPrefix(prefix) {
+  if (prefix === void 0) return void 0;
+  for (const ch of prefix) {
+    if (ch.charCodeAt(0) < 32) {
+      throw new ValidationError("prefix must not contain control characters");
+    }
+  }
+  for (const segment of prefix.split("/")) {
+    if (segment === "." || segment === "..") {
+      throw new ValidationError(
+        `prefix must not contain "." or ".." path segments: ${JSON.stringify(prefix)}`
+      );
+    }
+  }
+  return prefix;
+}
+function segmentObjectPrefix(prefix, ref) {
+  validateSegmentRef(ref);
+  return `${prefixPart(prefix)}${namespacePart(ref.namespace)}/segments/${ref.segment}.`;
+}
+function coldObjectName(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/drivers/gcs/gcs-errors.ts
+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 isNotFound(err) {
+  return httpStatus(err) === 404;
+}
+function isInvalidRange(err) {
+  return httpStatus(err) === 416;
+}
+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;
+  const net = networkCode(err);
+  return net === "ECONNRESET" || net === "ETIMEDOUT" || net === "ECONNREFUSED" || net === "EPIPE" || net === "EAI_AGAIN" || net === "ENOTFOUND";
+}
+
+// src/drivers/gcs/cold.ts
+var DEFAULT_MAX_OBJECT_BYTES = 5 * 1024 * 1024 * 1024 * 1024;
+var DEFAULT_UPLOAD_THRESHOLD_BYTES = 8 * 1024 * 1024;
+var GcsColdDriver = class {
+  storage;
+  bucket;
+  prefix;
+  maxObjectBytes;
+  threshold;
+  constructor(options) {
+    this.storage = options.storage;
+    this.bucket = options.bucket;
+    this.prefix = normalizeGcsPrefix(options.prefix);
+    this.maxObjectBytes = options.maxObjectBytes ?? DEFAULT_MAX_OBJECT_BYTES;
+    this.threshold = options.simpleUploadThresholdBytes ?? DEFAULT_UPLOAD_THRESHOLD_BYTES;
+  }
+  capabilities() {
+    return { rangeRead: true, maxObjectBytes: this.maxObjectBytes, conditionalPut: true };
+  }
+  file(name) {
+    return this.storage.bucket(this.bucket).file(name);
+  }
+  async putImmutable(key, write) {
+    const objectName = coldObjectName(this.prefix, key);
+    const sink = new GcsUploadSink(this.file(objectName), this.maxObjectBytes, this.threshold);
+    try {
+      await write(sink);
+      return await sink.finish();
+    } catch (err) {
+      await sink.abort();
+      if (isPreconditionFailed(err)) {
+        throw new WriteConflictError(
+          `generation already exists (write-once): ${key.segment}.${key.generation}`
+        );
+      }
+      if (isValidationError(err) || isWriteConflictError(err) || isNotFoundError(err)) throw err;
+      throw this.mapError(err);
+    }
+  }
+  async getRange(key, offset, length) {
+    if (!Number.isInteger(offset) || !Number.isInteger(length) || offset < 0 || length < 0) {
+      throw new ValidationError(`invalid range offset=${offset} length=${length}`);
+    }
+    if (length === 0) return new Uint8Array(0);
+    const objectName = coldObjectName(this.prefix, key);
+    try {
+      const [buf] = await this.file(objectName).download({
+        start: offset,
+        end: offset + length - 1
+      });
+      if (buf.length !== length) {
+        throw new ValidationError(
+          `range [${offset}, ${offset + length}) out of bounds (got ${buf.length}B)`
+        );
+      }
+      return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+    } catch (err) {
+      throw this.mapReadError(err, key);
+    }
+  }
+  async getTail(key, maxBytes) {
+    const objectName = coldObjectName(this.prefix, key);
+    try {
+      const [meta] = await this.file(objectName).getMetadata();
+      const size = Number(meta.size ?? 0);
+      if (!Number.isSafeInteger(size) || size < 0) {
+        throw new ValidationError(`GCS returned an invalid object size: ${String(meta.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 };
+    } catch (err) {
+      throw this.mapReadError(err, key);
+    }
+  }
+  async delete(key) {
+    try {
+      await this.file(coldObjectName(this.prefix, key)).delete({ ignoreNotFound: true });
+    } catch (err) {
+      throw this.mapError(err);
+    }
+  }
+  async *list(ref) {
+    const prefix = segmentObjectPrefix(this.prefix, ref);
+    let files;
+    try {
+      [files] = await this.storage.bucket(this.bucket).getFiles({ prefix });
+    } catch (err) {
+      throw this.mapError(err);
+    }
+    for (const f of files) {
+      const generation = parseGenerationFromName(prefix, f.name);
+      if (generation !== null) {
+        yield { namespace: ref.namespace, segment: ref.segment, generation };
+      }
+    }
+  }
+  /** Map GCS read errors to the driver vocabulary; pass everything else through {@link mapError}. */
+  mapReadError(err, key) {
+    if (isValidationError(err)) return err;
+    if (isNotFound(err))
+      return new NotFoundError(`no such generation: ${key.segment}.${key.generation}`);
+    if (isInvalidRange(err)) {
+      return new ValidationError(`range out of bounds for ${key.segment}.${key.generation}`);
+    }
+    return this.mapError(err);
+  }
+  /**
+   * Reclassify a transient GCS fault (throttle/5xx/dropped connection) as a retryable {@link TransientError}
+   * so the retry decorator can ride it out; everything else propagates unchanged. The final fallback at every
+   * client-call site, so callers + the decorator only ever see typed errors.
+   */
+  mapError(err) {
+    if (isTransient(err)) {
+      return new TransientError(
+        `transient GCS fault: ${err?.code ?? "unknown"}`,
+        { cause: err }
+      );
+    }
+    return err;
+  }
+};
+function concatBytes(parts, total) {
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const p of parts) {
+    out.set(p, offset);
+    offset += p.length;
+  }
+  return out;
+}
+var GcsUploadSink = class _GcsUploadSink {
+  constructor(file, maxObjectBytes, threshold) {
+    this.file = file;
+    this.maxObjectBytes = maxObjectBytes;
+    this.threshold = threshold;
+  }
+  file;
+  maxObjectBytes;
+  threshold;
+  hash = createHash("sha256");
+  total = 0;
+  buffered = [];
+  bufferedLen = 0;
+  stream;
+  // set once we cross the threshold → resumable mode
+  done;
+  failure;
+  static WRITE_OPTS = {
+    preconditionOpts: { ifGenerationMatch: 0 },
+    // write-once: create only if absent
+    metadata: { contentType: "application/octet-stream" }
+  };
+  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 ValidationError(`object exceeds maxObjectBytes ${this.maxObjectBytes}`);
+    }
+    this.hash.update(bytes);
+    if (this.stream !== void 0) {
+      if (!this.stream.write(bytes)) await once(this.stream, "drain");
+      return;
+    }
+    this.buffered.push(bytes);
+    this.bufferedLen += bytes.length;
+    if (this.bufferedLen > this.threshold) this.startResumable();
+  }
+  /** 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 });
+    this.stream = stream;
+    this.done = once(stream, "finish");
+    stream.on("error", (e) => {
+      this.failure ??= e;
+    });
+    this.done.catch(() => void 0);
+    const buf = concatBytes(this.buffered, this.bufferedLen);
+    this.buffered.length = 0;
+    this.bufferedLen = 0;
+    stream.write(buf);
+  }
+  async finish() {
+    if (this.failure !== void 0) throw this.failure;
+    const sha256 = this.hash.digest("hex");
+    if (this.stream === void 0) {
+      await this.file.save(concatBytes(this.buffered, this.bufferedLen), {
+        resumable: false,
+        ..._GcsUploadSink.WRITE_OPTS
+      });
+      return { size: this.total, sha256 };
+    }
+    this.stream.end();
+    await this.done;
+    return { size: this.total, sha256 };
+  }
+  async abort() {
+    if (this.stream !== void 0 && !this.stream.destroyed) this.stream.destroy();
+  }
+};
+
+export { GcsColdDriver };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/gcs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/drivers/gcs/keys.ts","../../src/drivers/gcs/gcs-errors.ts","../../src/drivers/gcs/cold.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Logical-ref → GCS object-name mapping for {@link GcsColdDriver} (Phase 7).\n *\n * Pure string logic, no SDK dependency — unit-testable without GCS or an emulator. Uses the **same\n * backend-agnostic `.crbm` object-name scheme** as the S3 + LocalFs cold drivers\n * (`<prefix><ns>/segments/<segment>.<gen>.crbm`), so a segment reads identically whichever cold backend holds\n * it. The default (absent) namespace maps to `_default` (the grammar forbids a leading underscore, so it can't\n * collide with a real namespace).\n *\n * NOTE (DRY): this mirrors the pure cold-key builders in `drivers/s3/keys.ts`. They are deliberately **not**\n * shared across driver folders today — a driver must stay self-contained so it lifts cleanly into its own\n * package at the [Phase 9 split]. At that split the shared cold-key\n * scheme is promoted into `@cloudbitmaps/core`'s driver-kit (imported by every driver package), which is the\n * right home for it; until then a self-contained copy beats a cross-driver import.\n */\nimport { ValidationError } from '@/core/errors';\nimport { validateSegmentRef } from '@/core/validate';\nimport type { GenKey, SegmentRef } from '@/core/ports';\nimport { namespacePart } from '../_shared/keys';\n\nconst SUFFIX = '.crbm';\n\n/** Normalize an optional caller prefix to either `''` or `trimmed/` (no leading/trailing slashes). */\nfunction prefixPart(prefix: string | undefined): string {\n  if (prefix === undefined) return '';\n  const trimmed = prefix.replace(/^\\/+|\\/+$/g, '');\n  return trimmed === '' ? '' : `${trimmed}/`;\n}\n\n/**\n * Validate the caller-supplied key prefix (trusted config, but a real containment boundary): reject control\n * characters and `.`/`..` path segments so a prefix can't traverse out of its intended space. Returns it\n * unchanged (the key builders normalize slashes).\n */\nexport function normalizeGcsPrefix(prefix: string | undefined): string | undefined {\n  if (prefix === undefined) return undefined;\n  for (const ch of prefix) {\n    if (ch.charCodeAt(0) < 0x20) {\n      throw new ValidationError('prefix must not contain control characters');\n    }\n  }\n  for (const segment of prefix.split('/')) {\n    if (segment === '.' || segment === '..') {\n      throw new ValidationError(\n        `prefix must not contain \".\" or \"..\" path segments: ${JSON.stringify(prefix)}`,\n      );\n    }\n  }\n  return prefix;\n}\n\n/**\n * The GCS object-name prefix shared by all of a segment's generations: `<prefix><ns>/segments/<segment>.`.\n * Used both as the `getFiles` prefix and as the string stripped by {@link parseGenerationFromName}.\n */\nexport function segmentObjectPrefix(prefix: string | undefined, ref: SegmentRef): string {\n  validateSegmentRef(ref);\n  return `${prefixPart(prefix)}${namespacePart(ref.namespace)}/segments/${ref.segment}.`;\n}\n\n/** The full GCS object name of one `.crbm` generation: `<segmentPrefix><gen>.crbm`. */\nexport function coldObjectName(prefix: string | undefined, key: GenKey): string {\n  if (!Number.isInteger(key.generation) || key.generation < 0) {\n    throw new ValidationError(`generation must be a non-negative integer; got ${key.generation}`);\n  }\n  return `${segmentObjectPrefix(prefix, key)}${key.generation}${SUFFIX}`;\n}\n\n/**\n * Parse a generation number out of a full object name, given its segment prefix, or `null` if it doesn't\n * match. Canonical decimal only — no leading zeros (so `…s.07.crbm` can't alias `…s.7.crbm`) and within\n * safe-integer range. Also rejects a *different* segment whose name merely shares the prefix (its middle\n * isn't all digits).\n */\nexport function parseGenerationFromName(segmentPrefix: string, objectName: string): number | null {\n  if (!objectName.startsWith(segmentPrefix) || !objectName.endsWith(SUFFIX)) return null;\n  const middle = objectName.slice(segmentPrefix.length, objectName.length - SUFFIX.length);\n  if (!/^(0|[1-9]\\d*)$/.test(middle)) return null;\n  const generation = Number(middle);\n  return Number.isSafeInteger(generation) ? generation : null;\n}\n","/**\n * Pure helpers for classifying Google Cloud Storage SDK errors (Phase 7; transient class mirrors S3's).\n *\n * SDK-free + side-effect-free — they only read structural shapes off the thrown value (`err.code`,\n * `err.response.status`, `err.name`), so the GCS-specific translation is unit-testable without a live GCS or\n * an emulator, and without importing `@google-cloud/storage`. GCS's `ApiError` carries the HTTP status on\n * `.code` (a number); dropped/timed-out sockets surface as a Node error with a string `.code` (`ECONNRESET`,\n * `ETIMEDOUT`, …).\n */\n\n/** The HTTP status of a GCS `ApiError`, if present (`err.code` as a number, or `err.response.status`). */\nfunction httpStatus(err: unknown): number | undefined {\n  const e = err as { code?: unknown; response?: { status?: unknown } } | null;\n  if (typeof e?.code === 'number') return e.code;\n  if (typeof e?.response?.status === 'number') return e.response.status;\n  return undefined;\n}\n\n/** A network-level error `code` string (e.g. `ECONNRESET`, `ETIMEDOUT`, `EAI_AGAIN`, `EPIPE`). */\nfunction networkCode(err: unknown): string | undefined {\n  const code = (err as { code?: unknown } | null)?.code;\n  return typeof code === 'string' ? code : undefined;\n}\n\n/**\n * A conditional `ifGenerationMatch: 0` write lost the write-once race — the object already existed, so GCS\n * returns **412 Precondition Failed**. Maps to `WriteConflictError` (caller OCC), never a blind retry.\n */\nexport function isPreconditionFailed(err: unknown): boolean {\n  return httpStatus(err) === 412;\n}\n\n/** The object / generation does not exist (GCS returns 404). */\nexport function isNotFound(err: unknown): boolean {\n  return httpStatus(err) === 404;\n}\n\n/** A range request started past EOF (HTTP 416 Requested Range Not Satisfiable). */\nexport function isInvalidRange(err: unknown): boolean {\n  return httpStatus(err) === 416;\n}\n\n/**\n * A transient GCS fault that is safe to retry: throttling (429), any 5xx, or a dropped/timed-out socket.\n * Excludes the deterministic, caller-meaningful outcomes (412/404/416) — those must never be reclassified as\n * a blind transient (a retried doomed conditional write would just fail again, and mask an OCC conflict).\n */\nexport function isTransient(err: unknown): boolean {\n  if (isPreconditionFailed(err) || isNotFound(err) || isInvalidRange(err)) return false;\n  const status = httpStatus(err);\n  if (status === 429 || (status !== undefined && status >= 500 && status < 600)) return true;\n  const net = networkCode(err);\n  return (\n    net === 'ECONNRESET' ||\n    net === 'ETIMEDOUT' ||\n    net === 'ECONNREFUSED' ||\n    net === 'EPIPE' ||\n    net === 'EAI_AGAIN' ||\n    net === 'ENOTFOUND'\n  );\n}\n","/**\n * `GcsColdDriver` — an {@link IColdDriver} over Google Cloud Storage (Phase 7).\n *\n * Uses the official `@google-cloud/storage`, an **optional peer dependency** — only consumers of\n * `cloud-roaring/gcs` install it. The `Storage` client is **injected** (dependency injection): the driver owns\n * no credential/project/endpoint logic, so it's thin, reuses the caller's client, and is testable against the\n * `fake-gcs-server` emulator (point a `Storage` at its `apiEndpoint`).\n *\n * Generations are write-once immutable objects: a resumable upload with the **`ifGenerationMatch: 0`**\n * precondition (\"create only if it does not exist\") makes the publish atomic — a second write to the same\n * object fails with 412 → {@link WriteConflictError}, never a silent overwrite (C13), the GCS analogue of S3's\n * `If-None-Match: *` and LocalFs's atomic `link`. **Writes stream in constant memory:** the codec's bytes are\n * piped into a GCS resumable-upload `Writable` (chunked/freed by the SDK as they go), so the daemon's write\n * footprint stays bounded regardless of segment size, up to the advertised `maxObjectBytes`. Drivers may use\n * `node:crypto`; only `core/` is bound by the determinism lint.\n */\nimport { createHash, type Hash } from 'node:crypto';\nimport type { Writable } from 'node:stream';\nimport { once } from 'node:events';\nimport type { Storage } from '@google-cloud/storage';\nimport type { BlobSink } from '@/core/blob';\nimport {\n  NotFoundError,\n  TransientError,\n  ValidationError,\n  WriteConflictError,\n  isNotFoundError,\n  isValidationError,\n  isWriteConflictError,\n} from '@/core/errors';\nimport type { ColdCaps, GenKey, IColdDriver, SegmentRef } from '@/core/ports';\nimport {\n  coldObjectName,\n  normalizeGcsPrefix,\n  parseGenerationFromName,\n  segmentObjectPrefix,\n} from './keys';\nimport { isInvalidRange, isNotFound, isPreconditionFailed, isTransient } from './gcs-errors';\n\n/** Default object ceiling: GCS's 5 TiB per-object hard max. Set lower to fail fast on a runaway write. */\nconst DEFAULT_MAX_OBJECT_BYTES = 5 * 1024 * 1024 * 1024 * 1024;\n\n/**\n * Objects at/under this size are uploaded in a **single simple (non-resumable) request**; larger ones switch to\n * a **resumable stream** (constant memory). Mirrors S3's single-PUT-vs-multipart split — the simple path buffers\n * only ≤ this many bytes, the resumable path streams. Default 8 MiB (≈ S3's part size), so peak write memory is\n * ~one threshold's worth regardless of object size.\n */\nconst DEFAULT_UPLOAD_THRESHOLD_BYTES = 8 * 1024 * 1024;\n\nexport interface GcsColdDriverOptions {\n  /** A constructed `@google-cloud/storage` `Storage` client (point `apiEndpoint` at fake-gcs-server locally). */\n  readonly storage: Storage;\n  /** Target bucket (must already exist). */\n  readonly bucket: string;\n  /** Optional object-name prefix under which all objects live (e.g. `cloudroaring/`). */\n  readonly prefix?: string;\n  /** Largest object this driver will write/advertise (default = GCS's 5 TiB max). */\n  readonly maxObjectBytes?: number;\n  /** Bytes at/under which a single non-resumable upload is used instead of a resumable stream (default 8 MiB). */\n  readonly simpleUploadThresholdBytes?: number;\n}\n\nexport class GcsColdDriver implements IColdDriver {\n  private readonly storage: Storage;\n  private readonly bucket: string;\n  private readonly prefix: string | undefined;\n  private readonly maxObjectBytes: number;\n  private readonly threshold: number;\n\n  constructor(options: GcsColdDriverOptions) {\n    this.storage = options.storage;\n    this.bucket = options.bucket;\n    this.prefix = normalizeGcsPrefix(options.prefix);\n    this.maxObjectBytes = options.maxObjectBytes ?? DEFAULT_MAX_OBJECT_BYTES;\n    this.threshold = options.simpleUploadThresholdBytes ?? DEFAULT_UPLOAD_THRESHOLD_BYTES;\n  }\n\n  capabilities(): ColdCaps {\n    return { rangeRead: true, maxObjectBytes: this.maxObjectBytes, conditionalPut: true };\n  }\n\n  private file(name: string) {\n    return this.storage.bucket(this.bucket).file(name);\n  }\n\n  async putImmutable(\n    key: GenKey,\n    write: (sink: BlobSink) => Promise<void>,\n  ): Promise<{ size: number; sha256: string }> {\n    const objectName = coldObjectName(this.prefix, key); // validates ref + generation\n    const sink = new GcsUploadSink(this.file(objectName), this.maxObjectBytes, this.threshold);\n    try {\n      await write(sink);\n      return await sink.finish();\n    } catch (err) {\n      await sink.abort(); // best-effort teardown of the in-flight upload\n      // A lost write-once race — the object already existed, so `ifGenerationMatch: 0` failed with 412.\n      if (isPreconditionFailed(err)) {\n        throw new WriteConflictError(\n          `generation already exists (write-once): ${key.segment}.${key.generation}`,\n        );\n      }\n      if (isValidationError(err) || isWriteConflictError(err) || isNotFoundError(err)) throw err;\n      throw this.mapError(err);\n    }\n  }\n\n  async getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array> {\n    if (!Number.isInteger(offset) || !Number.isInteger(length) || offset < 0 || length < 0) {\n      throw new ValidationError(`invalid range offset=${offset} length=${length}`);\n    }\n    if (length === 0) return new Uint8Array(0);\n    const objectName = coldObjectName(this.prefix, key);\n    try {\n      // GCS `end` is inclusive.\n      const [buf] = await this.file(objectName).download({\n        start: offset,\n        end: offset + length - 1,\n      });\n      // A short read means the range ran past EOF — treat as out-of-bounds, never a partial result.\n      if (buf.length !== length) {\n        throw new ValidationError(\n          `range [${offset}, ${offset + length}) out of bounds (got ${buf.length}B)`,\n        );\n      }\n      return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);\n    } catch (err) {\n      throw this.mapReadError(err, key);\n    }\n  }\n\n  async getTail(key: GenKey, maxBytes: number): Promise<{ bytes: Uint8Array; size: number }> {\n    const objectName = coldObjectName(this.prefix, key);\n    try {\n      // Two round-trips (metadata for the size, then a ranged download) vs S3's one (suffix-range +\n      // Content-Range). This is on the per-*generation* open path, which the reader caches — NOT the per-op hot\n      // path (add/has/count/intersect) — so it's amortized; collapsing to one RT is a tracked follow-up.\n      const [meta] = await this.file(objectName).getMetadata();\n      const size = Number(meta.size ?? 0);\n      if (!Number.isSafeInteger(size) || size < 0) {\n        throw new ValidationError(`GCS returned an invalid object size: ${String(meta.size)}`);\n      }\n      if (maxBytes <= 0 || size === 0) return { bytes: new Uint8Array(0), size };\n      const start = Math.max(0, size - maxBytes);\n      const [buf] = await this.file(objectName).download({ start, end: size - 1 });\n      return { bytes: new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength), size };\n    } catch (err) {\n      throw this.mapReadError(err, key);\n    }\n  }\n\n  async delete(key: GenKey): Promise<void> {\n    // Idempotent: `ignoreNotFound` so a racing/retried GC sweep of an absent object is a no-op.\n    try {\n      await this.file(coldObjectName(this.prefix, key)).delete({ ignoreNotFound: true });\n    } catch (err) {\n      throw this.mapError(err);\n    }\n  }\n\n  async *list(ref: SegmentRef): AsyncIterable<GenKey> {\n    const prefix = segmentObjectPrefix(this.prefix, ref); // validates ref\n    let files;\n    try {\n      // autoPaginate (default) drains every page; a segment has few generations, so the set is small.\n      [files] = await this.storage.bucket(this.bucket).getFiles({ prefix });\n    } catch (err) {\n      throw this.mapError(err);\n    }\n    for (const f of files) {\n      const generation = parseGenerationFromName(prefix, f.name);\n      if (generation !== null) {\n        yield { namespace: ref.namespace, segment: ref.segment, generation };\n      }\n    }\n  }\n\n  /** Map GCS read errors to the driver vocabulary; pass everything else through {@link mapError}. */\n  private mapReadError(err: unknown, key: GenKey): unknown {\n    if (isValidationError(err)) return err;\n    if (isNotFound(err))\n      return new NotFoundError(`no such generation: ${key.segment}.${key.generation}`);\n    // A fully out-of-range request (start past EOF) — the BlobReader contract treats range errors as\n    // ValidationError, never a short/empty read.\n    if (isInvalidRange(err)) {\n      return new ValidationError(`range out of bounds for ${key.segment}.${key.generation}`);\n    }\n    return this.mapError(err);\n  }\n\n  /**\n   * Reclassify a transient GCS fault (throttle/5xx/dropped connection) as a retryable {@link TransientError}\n   * so the retry decorator can ride it out; everything else propagates unchanged. The final fallback at every\n   * client-call site, so callers + the decorator only ever see typed errors.\n   */\n  private mapError(err: unknown): unknown {\n    if (isTransient(err)) {\n      return new TransientError(\n        `transient GCS fault: ${(err as { code?: unknown } | null)?.code ?? 'unknown'}`,\n        { cause: err },\n      );\n    }\n    return err;\n  }\n}\n\ntype GcsFile = ReturnType<ReturnType<Storage['bucket']>['file']>;\n\n/** Concatenate byte chunks of known total length into one buffer. */\nfunction concatBytes(parts: readonly Uint8Array[], total: number): Uint8Array {\n  const out = new Uint8Array(total);\n  let offset = 0;\n  for (const p of parts) {\n    out.set(p, offset);\n    offset += p.length;\n  }\n  return out;\n}\n\n/**\n * {@link BlobSink} that uploads one GCS object write-once. It **buffers up to a threshold**: an object that\n * finishes at/under it is committed in a **single simple (non-resumable) request** (`file.save`) — the write-once\n * path both real GCS and `fake-gcs-server` enforce; a larger one switches to a **resumable stream**, flushing the\n * buffer then piping the rest in constant memory (peak ≈ one threshold). SHA-256 is hashed incrementally. Both\n * paths carry `ifGenerationMatch: 0` (create-only-if-absent) → a conflict is a 412, mapped by the driver to\n * {@link WriteConflictError}. On error the caller invokes {@link abort}.\n */\nclass GcsUploadSink implements BlobSink {\n  private readonly hash: Hash = createHash('sha256');\n  private total = 0;\n  private readonly buffered: Uint8Array[] = [];\n  private bufferedLen = 0;\n  private stream: Writable | undefined; // set once we cross the threshold → resumable mode\n  private done: Promise<unknown[]> | undefined;\n  private failure: unknown;\n\n  constructor(\n    private readonly file: GcsFile,\n    private readonly maxObjectBytes: number,\n    private readonly threshold: number,\n  ) {}\n\n  private static readonly WRITE_OPTS = {\n    preconditionOpts: { ifGenerationMatch: 0 as const }, // write-once: create only if absent\n    metadata: { contentType: 'application/octet-stream' },\n  };\n\n  async write(bytes: Uint8Array): Promise<void> {\n    if (this.failure !== undefined) throw this.failure;\n    if (bytes.length === 0) return;\n    this.total += bytes.length;\n    if (this.total > this.maxObjectBytes) {\n      throw new ValidationError(`object exceeds maxObjectBytes ${this.maxObjectBytes}`);\n    }\n    this.hash.update(bytes);\n    if (this.stream !== undefined) {\n      // Resumable mode: honor backpressure. `events.once(stream,'drain')` REJECTS if the stream emits 'error'\n      // while we wait (that's its documented behavior for any awaited event except 'error'), and auto-removes\n      // both listeners on settle — so there's no listener accumulation across drain cycles.\n      if (!this.stream.write(bytes)) await once(this.stream, 'drain');\n      return;\n    }\n    this.buffered.push(bytes);\n    this.bufferedLen += bytes.length;\n    if (this.bufferedLen > this.threshold) this.startResumable();\n  }\n\n  /** Cross into resumable streaming: open the stream, flush the buffered bytes, keep only ~one threshold resident. */\n  private startResumable(): void {\n    const stream = this.file.createWriteStream({ resumable: true, ...GcsUploadSink.WRITE_OPTS });\n    this.stream = stream;\n    this.done = once(stream, 'finish'); // resolves on a clean commit; rejects on 'error' (e.g. 412)\n    stream.on('error', (e: unknown) => {\n      this.failure ??= e; // a persistent listener so a stray 'error' is never an unhandled 'error' event\n    });\n    this.done.catch(() => undefined); // finish() awaits this; guard against unhandled rejection until then\n    const buf = concatBytes(this.buffered, this.bufferedLen);\n    this.buffered.length = 0;\n    this.bufferedLen = 0;\n    stream.write(buf); // ≤ threshold+one-chunk; backpressure is absorbed by the next write()'s drain-await / end()\n  }\n\n  async finish(): Promise<{ size: number; sha256: string }> {\n    if (this.failure !== undefined) throw this.failure;\n    const sha256 = this.hash.digest('hex');\n    if (this.stream === undefined) {\n      // Small object: a single simple (non-resumable) upload — write-once enforced everywhere (incl. the emulator).\n      await this.file.save(concatBytes(this.buffered, this.bufferedLen), {\n        resumable: false,\n        ...GcsUploadSink.WRITE_OPTS,\n      });\n      return { size: this.total, sha256 };\n    }\n    this.stream.end();\n    await this.done; // rejects if the commit fails (e.g. 412 write-once conflict)\n    return { size: this.total, sha256 };\n  }\n\n  async abort(): Promise<void> {\n    if (this.stream !== undefined && !this.stream.destroyed) this.stream.destroy();\n  }\n}\n"]}