@cloudbitmaps/gcs 0.21.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbitmaps/gcs",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Google Cloud Storage for CloudBitmaps",
   "keywords": [
     "cloudbitmaps",
@@ -36,7 +36,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -49,7 +50,7 @@
   },
   "dependencies": {
     "@google-cloud/storage": "^7 || ^8",
-    "@cloudbitmaps/core": "^0.21.0"
+    "@cloudbitmaps/core": "0.23.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/dist/bucket-presence.d.ts

@@ -1,37 +0,0 @@
-/**
- * Whether the bucket a driver names exists, asked when a request first answers 404.
- *
- * GCS answers a missing bucket and a missing object with the same status and reason (`404 notFound`), and a
- * GCS-compatible server may not even word them apart. Read as a missing object, a misnamed or deleted bucket would
- * answer every read as an empty segment. An object listing tells them apart: it names no object, so its 404 can only
- * be the bucket's.
- *
- * ```
- *   a request answers 404 ──▶ confirm() ──▶ bucket seen before? ── yes ──▶ the 404 is an object's
- *                                              │ no
- *                                              ▼
- *                              list one object in the bucket
- *                               ├─ answered ──────────▶ remember the bucket; the 404 is an object's
- *                               ├─ 404 ───────────────▶ reject: ValidationError, the bucket does not exist
- *                               ├─ transient ─────────▶ reject: TransientError (asked again next time)
- *                               ├─ 403 ───────────────▶ remember it as unknowable; the 404 is an object's
- *                               └─ anything else ─────▶ the 404 is an object's (asked again next time)
- * ```
- *
- * A process pays one listing at most while its bucket exists, and concurrent 404s share it. An identity without
- * `storage.objects.list` is answered `403`, which says nothing about the bucket, so its 404s read as they always did.
- * Any other failure (a credential that could not be fetched, a 401) says nothing either, but may not last, so it is
- * not remembered. Once seen, the bucket is not asked about again: one deleted later in the process's life reads as an
- * empty store, as it did before this check, while every write to it fails.
- */
-import type { Storage } from '@google-cloud/storage';
-export declare class BucketPresence {
-    private readonly storage;
-    private readonly bucket;
-    private settled;
-    private asking;
-    constructor(storage: Storage, bucket: string);
-    /** Resolve when a 404 can be read as an object's; reject with `ValidationError` when the bucket does not exist, `TransientError` when the listing failed in transit. */
-    confirm(): Promise<void>;
-    private ask;
-}

package/dist/crc32c.d.ts

@@ -1,5 +0,0 @@
-/**
- * CRC32C (Castagnoli) of some bytes, in the form GCS takes in an object's `crc32c` metadata: the 4-byte big-endian
- * value, base64-encoded. Computed here rather than through the SDK so it is the same on every major the driver accepts.
- */
-export declare function crc32cBase64(bytes: Uint8Array): string;

package/dist/defined.d.ts

@@ -1,8 +0,0 @@
-/**
- * `values` without the entries that are `undefined`, typed as optional properties, so a constructor can pass on the
- * options it was given: `exactOptionalPropertyTypes` refuses `{ x: undefined }` for an optional `x`, and a sub-driver
- * must see an option the caller left out as absent.
- */
-export declare function defined<T extends Record<string, unknown>>(values: T): {
-    [K in keyof T]?: Exclude<T[K], undefined>;
-};

package/dist/download-retry.d.ts

@@ -1,8 +0,0 @@
-import { type Deadline } from './read-timeout.js';
-/** Under a deadline, a retry is not sent with less than this left of it. */
-export declare const MIN_RETRY_MS = 10;
-/**
- * Call `download`, and again after each retryable fault, up to {@link RETRIES} more times, within `deadline` when there
- * is one; rethrow the last error, or the deadline's once it has passed.
- */
-export declare function retryDownload<T>(download: () => Promise<T>, deadline?: Deadline): Promise<T>;

package/dist/gcs-errors.d.ts

@@ -1,60 +0,0 @@
-/**
- * Pure helpers for classifying Google Cloud Storage SDK errors (the transient class mirrors S3's).
- *
- * SDK-free + side-effect-free — they only read structural shapes off the thrown value (`err.code`,
- * `err.response.status`, `err.name`), so the GCS-specific translation is unit-testable without a live GCS or
- * an emulator, and without importing `@google-cloud/storage`. GCS's `ApiError` carries the HTTP status on
- * `.code` (a number); dropped/timed-out sockets surface as a Node error with a string `.code` (`ECONNRESET`,
- * `ETIMEDOUT`, …).
- */
-import { ValidationError } from '@cloudbitmaps/core/driver-kit';
-/**
- * A conditional `ifGenerationMatch: 0` write lost the write-once race — the object already existed, so GCS
- * returns **412 Precondition Failed**. Maps to `WriteConflictError` (caller OCC), never a blind retry.
- */
-export declare function isPreconditionFailed(err: unknown): boolean;
-/**
- * GCS asked the client to slow down: `429` (`rateLimitExceeded`) or `503` (`backendError`), which the SDK raises as an
- * `ApiError` with the status as a numeric `code`. GCS does not document that a throttled request was not applied, so
- * an upload sent again after one must still tell a landed first send apart.
- */
-export declare function isThrottle(err: unknown): boolean;
-/** The object / generation does not exist (GCS returns 404), in a bucket that does. */
-export declare function isNotFound(err: unknown): boolean;
-/**
- * The bucket itself does not exist: a wiring fault, never an absent object. Read as one, a misnamed or deleted bucket
- * would answer every read as an empty segment. GCS gives both the same status and reason (`404 notFound`), so only its
- * message tells them apart: on a download the message is the response body as it came, JSON or text, and elsewhere
- * the message and each `errors[].message` are GCS's own. A wording this does not match reads as an absent object.
- */
-export declare function isMissingBucket(err: unknown): boolean;
-/**
- * The {@link ValidationError} a missing bucket is: it names the bucket and what to check, and carries the service's
- * error as its `cause`. A wiring fault is not an absent object, so it is not a `NotFoundError`: a read re-resolves on
- * that, and would treat a misnamed bucket as a miss it can heal.
- */
-export declare function missingBucketError(bucket: string, cause: unknown): ValidationError;
-/** `err`, or {@link missingBucketError} when `err` says the bucket does not exist. */
-export declare function asMissingBucket(err: unknown, bucket: string): unknown;
-/** A range request started past EOF (HTTP 416 Requested Range Not Satisfiable). */
-export declare function isInvalidRange(err: unknown): boolean;
-/** A download that failed in transit rather than with an HTTP status: a connection fault ({@link isConnectionFault}). */
-export declare function isTransportFault(err: unknown): boolean;
-/**
- * Whether the driver retries a failed download, which it does in the SDK's place: the statuses the SDK's predicate
- * retries (408, 429, 500, 502, 503 and 504, as a number or a string `code`), the connection faults it names in any
- * `errors[].reason`, and every {@link isTransportFault}, which the SDK retried before any response came. A 404, 412,
- * 416 or 403, a 501 or 505, a credentials or TLS failure, and every other answer reach the caller on the first attempt.
- */
-export declare function isDownloadRetryable(err: unknown): boolean;
-/**
- * A transient GCS fault that is safe to retry: throttling (429), a request timeout (408), any 5xx, or a dropped/timed-out socket.
- * Excludes the deterministic, caller-meaningful outcomes (412/404/416) — those must never be reclassified as
- * a blind transient (a retried doomed conditional write would just fail again, and mask an OCC conflict).
- */
-export declare function isTransient(err: unknown): boolean;
-/**
- * The message a transient GCS fault is handed on with: `transient GCS fault: <code>`, the HTTP status the SDK puts on
- * `code` or Node's connection code, else the error's name.
- */
-export declare function transientFaultMessage(err: unknown): string;

package/dist/read-client.d.ts

@@ -1,6 +0,0 @@
-import type { Storage } from '@google-cloud/storage';
-/**
- * A twin of `client` that sends each download once, or `client` itself when it is a test double whose retries are off.
- * `supplied`: the caller handed `client` in, rather than the backend building it.
- */
-export declare function downloadClient(client: Storage, supplied: boolean): Storage;

package/dist/read-once.d.ts

@@ -1,52 +0,0 @@
-/**
- * `readOnce` — read one object, or one range of it, in a single GET, with the response headers in hand.
- *
- * `file.download()` returns only the bytes. The headers carry what a caller needs alongside them — the object's
- * `generation` (the registry's version fence) and, on a ranged read, the object's total size in `Content-Range` — so
- * this reads through `createReadStream`, which announces the raw response before any data flows. Both come from the
- * same response as the bytes, so they describe one observation of the object.
- *
- * **Everything on the wire is untrusted.** The advertised `Content-Length` is checked against `maxBytes` before the
- * first byte is buffered, and the bytes are counted as they arrive, so a response that understates its length (or
- * omits it) still cannot make the caller hold more than `maxBytes`. The headers are returned as received; each caller
- * parses the ones it relies on strictly.
- *
- * **Every download stays off the SDK's shared connection pool.** When a download fails part-way — a body cut off, a
- * refused response, a timeout — the SDK destroys the HTTP agent the request went out on, to free its socket. By default
- * that is one keep-alive agent the whole process shares (teeny-request's, for every request with `forever: true`), so
- * every other request in flight on any client is reset with it, uploads included. {@link downloadFile} sets
- * `forever: false` on its own requests, through the SDK's request interceptors: they then go out on Node's global
- * agent, which the SDK never destroys, and on `@google-cloud/storage` 8.x a destroyed download closes its own socket
- * and nothing else. The cost: the global agent closes a connection idle for 5 seconds, where the SDK's pool keeps it,
- * so a read after a longer pause opens a new one; and it is shared with the process's other `http` and `https` code.
- */
-import type { Storage } from '@google-cloud/storage';
-import type { Deadline } from './read-timeout.js';
-type GcsFile = ReturnType<ReturnType<Storage['bucket']>['file']>;
-/** A handle on `name` for downloading: its requests stay off the SDK's shared agent. The client is not touched. */
-export declare function downloadFile(storage: Storage, bucket: string, name: string): GcsFile;
-export interface ObjectRead {
-    /** The HTTP status of the response (200 for a whole object, 206 for a range). */
-    readonly status: number;
-    /** The response headers, lower-cased as Node delivers them. */
-    readonly headers: Readonly<Record<string, string | string[] | undefined>>;
-    /** The body, at most `maxBytes` long. */
-    readonly bytes: Uint8Array;
-}
-/** The value of a header that must appear once, or `undefined` when it is absent, repeated or empty. */
-export declare function singleHeader(headers: ObjectRead['headers'], name: string): string | undefined;
-/**
- * GET `file` (with the SDK's `createReadStream` options), buffering at most `maxBytes`. `oversize` builds the error
- * thrown when the advertised or actual length passes the cap, so each caller reports it in its own vocabulary.
- * Transport and HTTP errors reject as the SDK raises them (a 404 carries `code: 404`).
- *
- * With a `deadline`, a read still unsettled when it passes rejects with its `ReadTimedOut`; one asked for after it has
- * passed is not sent. The deadline belongs to the whole driver read, so an attempt gets only what is left of it.
- */
-export declare function readOnce(file: GcsFile, options: {
-    start?: number;
-    end?: number;
-    validation?: false;
-    decompress?: false;
-}, maxBytes: number, oversize: (size: number | undefined) => Error, deadline?: Deadline): Promise<ObjectRead>;
-export {};

package/dist/read-timeout.d.ts

@@ -1,28 +0,0 @@
-/** Validate a caller's `readTimeoutMs`, defaulting it: an integer from 0 (no timeout) to {@link MAX_TIMER_MS}. */
-export declare function resolveReadTimeoutMs(value: unknown): number;
-/** A read the driver gave up on when its deadline passed. Coded `ETIMEDOUT`, as a timed-out connection is. */
-export declare class ReadTimedOut extends Error {
-    readonly code = "ETIMEDOUT";
-    constructor(read: string, ms: number, cause?: unknown);
-}
-/** One driver read's deadline: `ms` from when it is made. `read` names the read in the error, e.g. `tail read of s.3`. */
-export declare class Deadline {
-    readonly ms: number;
-    readonly read: string;
-    private readonly endsAt;
-    constructor(ms: number, read: string);
-    /** What is left of it, in milliseconds: 0 once it has passed. */
-    remaining(): number;
-    /** The error a read fails with once this has passed; `cause` is the last attempt's own error, if one failed. */
-    expired(cause?: unknown): ReadTimedOut;
-}
-/** The deadline a read made now runs under, or none when `ms` is 0 (no timeout). */
-export declare function startDeadline(ms: number, read: string): Deadline | undefined;
-/**
- * Make the request `send` starts, and settle with it, or with {@link ReadTimedOut} once `deadline` has passed; a
- * deadline already passed sends nothing. For a request the SDK cannot cancel: a metadata read is one callback-style
- * request that returns no handle to abort it, so at the deadline this stops waiting and the request runs on until it is
- * answered or its connection closes. The race keeps a handler on the request, so what it settles with then is dropped
- * rather than raised.
- */
-export declare function withDeadline<T>(send: () => Promise<T>, deadline: Deadline | undefined): Promise<T>;

package/dist/registry.d.ts

@@ -1,90 +0,0 @@
-/**
- * `GcsRegistryDriver` — an {@link IRegistryDriver} over Google Cloud Storage.
- *
- * Lets a **GCS deployment run on one bucket alone** — storage `.crbm` generations and the registry in the same
- * place, with no second cloud involved.
- *
- * The protocol (an ABA-safe OCC token, the delete and its tombstone, the bounded retry, the key layout) lives once
- * in {@link ObjectStoreRegistry}; this file is only the I/O calls GCS makes. A delete removes a row for good, under
- * `ifGenerationMatch: <generation>`, when `conditionalDelete` is `true`. It is off by default, on the public endpoint too:
- * no run against real GCS has verified that the service applies the precondition to a delete, and fake-gcs-server
- * accepts it and ignores it, so CI cannot show it.
- *
- * **The atomic swap is offloaded to GCS's object preconditions.** `ifGenerationMatch: 0` is create-only
- * ("only if it does not exist") and `ifGenerationMatch: <generation>` is compare-and-swap — the same pair S3
- * spells `If-None-Match: *` / `If-Match: <etag>`. A lost race returns `412` → {@link WriteConflictError}. Each write
- * is one request sent once ({@link saveOnce}), so a `412` means another write got there first, never this one meeting
- * itself after a lost response. A transient failure reaches the caller as {@link TransientError}: the write may or may
- * not have landed, and the caller re-reads the row to learn where it stands.
- *
- * **The version fence is the object's `generation`, not its ETag**: GCS mutates the generation on every
- * overwrite and it is the value `ifGenerationMatch` compares, so it is the only correct fence here. (Note
- * the unrelated collision of vocabulary — a GCS *object generation* has nothing to do with a CloudBitmaps
- * `.crbm` *generation*.) Reads are strongly consistent, satisfying the registry's `strongRead` contract.
- *
- * **Deployment requirements** (a policy that violates these silently corrupts the registry):
- * - The principal needs `storage.objects.get`, `create`, `update`, `list` and, to remove rows, `delete` on the
- *   bucket. Without `list`
- *   the registry cannot enumerate, and a missing-object read may surface as `403` rather than `404`.
- * - **Do not apply an Object Lifecycle rule to the `registry/` prefix that deletes a live object** (one on
- *   noncurrent versions only is safe), and do not enable a retention
- *   policy that blocks overwrite or deletion; see {@link ObjectStoreRegistry}.
- * - Object versioning is neither required nor used; the driver always reads the live generation. A read is one
- *   GET whose `x-goog-generation` header and body describe the same object, so a concurrent overwrite is simply
- *   observed as the older or the newer row, never as a torn pair or a missing one.
- */
-import { ObjectStoreRegistry } from '@cloudbitmaps/core/driver-kit';
-import type { ObjectRegistryStore, ObjectRow } from '@cloudbitmaps/core/driver-kit';
-import type { Storage } from '@google-cloud/storage';
-interface GcsRegistryDriverOptions {
-    /** A constructed `@google-cloud/storage` `Storage` client (point `apiEndpoint` at fake-gcs-server locally). */
-    readonly storage: Storage;
-    /** The client the downloads go through; `storage` when absent (see `GcsStorageDriverOptions.readStorage`). */
-    readonly readStorage?: Storage;
-    /** Target bucket (must already exist). */
-    readonly bucket: string;
-    /** Optional object-name prefix under which all registry objects live (e.g. `cloudbitmaps/`). */
-    readonly prefix?: string;
-    /** Injected clock for `createdAt`/`updatedAt`; defaults to `Date.now`. */
-    readonly now?: () => number;
-    /**
-     * Cut off a read of a registry row once it has run this long, in milliseconds, every attempt included; `0` (the
-     * default) sets no timeout. Timed as the storage driver's reads are (see `GcsStorageDriverOptions.readTimeoutMs`);
-     * the writes and listings are not timed.
-     */
-    readonly readTimeoutMs?: number;
-    /**
-     * Whether a delete removes a row for good, by an object delete sent with `ifGenerationMatch: <the generation it
-     * read>`, rather than leaving a tombstone. Defaults to `false`, on the public endpoint too: whether real GCS applies
-     * `ifGenerationMatch` to a delete has not been verified by a run against the service, and fake-gcs-server accepts the
-     * precondition and ignores it, so CI cannot show it. Set `true` to remove rows for good.
-     */
-    readonly conditionalDelete?: boolean;
-}
-/** The calls {@link ObjectStoreRegistry} needs, in GCS's dialect. Exported for the tests that drive one directly. */
-export declare class GcsRegistryStore implements ObjectRegistryStore {
-    private readonly storage;
-    private readonly readStorage;
-    private readonly bucket;
-    private readonly readTimeoutMs;
-    readonly conditionalDelete: boolean;
-    readonly label = "GCS";
-    private readonly presence;
-    constructor(storage: Storage, readStorage: Storage, bucket: string, readTimeoutMs: number, conditionalDelete: boolean);
-    /** A handle on one registry object. */
-    private file;
-    /** The same file handle on the download client, off the SDK's shared agent ({@link downloadFile}). */
-    private downloadable;
-    read(key: string): Promise<ObjectRow | null>;
-    write(key: string, body: Uint8Array, expect: 'absent' | {
-        version: string;
-    }): Promise<void>;
-    delete(key: string, expect: {
-        version: string;
-    }): Promise<void>;
-    listKeys(prefix: string): AsyncIterable<string>;
-}
-export declare class GcsRegistryDriver extends ObjectStoreRegistry {
-    constructor(options: GcsRegistryDriverOptions);
-}
-export {};

package/dist/scrub-error.d.ts

@@ -1,18 +0,0 @@
-/**
- * Make an error the SDK raised safe to throw, or to keep as a `cause`: a copy of it with no credential and none of the
- * live transport.
- *
- * The SDK keeps the request it sent on the error (`response.request`, `config.headers`, the raw request line), and
- * through that request the HTTP agent it shares with every other call, whose sockets hold the raw text, bearer token
- * included, of requests still in flight. An application that logs the error or its cause chain would write a live
- * access token. The error is therefore replaced by a copy built from what it is: its prototype, name, message, stack,
- * code, status and other plain data; `response` reduced to its status; the request, agent, socket and config dropped.
- * Nothing live is ever changed, only read, and the copy is made from plain data alone, so no depth or size limit can
- * stop short of a secret. A credential header or header line in the plain data that is kept is redacted.
- */
-/**
- * `err` as it is safe to throw: a credential-free copy of an error that holds the SDK's request or response, and any
- * other value as it is (a timeout, a connection fault or an error of the driver's own holds no credential, and keeps
- * its identity).
- */
-export declare function scrubCredentials<T>(err: T): T;

package/dist/send-once.d.ts

@@ -1,5 +0,0 @@
-import type { CreateWriteStreamOptions, Storage } from '@google-cloud/storage';
-type GcsFile = ReturnType<ReturnType<Storage['bucket']>['file']>;
-/** Upload `body` to `file` in one request, sent once; resolves once GCS has stored it and its checksum matched. */
-export declare function saveOnce(file: GcsFile, body: Uint8Array, options: CreateWriteStreamOptions): Promise<void>;
-export {};

package/dist/storage.d.ts

@@ -1,109 +0,0 @@
-import type { BlobSink, GenKey, IStorageDriver, SegmentRef, StorageCaps, StorageDeleteOptions, TailRead } from '@cloudbitmaps/core/driver-kit';
-import type { Clock, Rng } from '@cloudbitmaps/core';
-import type { Storage } from '@google-cloud/storage';
-/** What the throttle backoff waits on. */
-type Sleeper = Pick<Clock, 'sleep'>;
-interface GcsStorageDriverOptions {
-    /** A constructed `@google-cloud/storage` `Storage` client (point `apiEndpoint` at fake-gcs-server locally). */
-    readonly storage: Storage;
-    /**
-     * The client the downloads go through; `storage` when absent. `GcsStorage` passes one built with the SDK's request
-     * retries off (the read client built in its constructor), because a download the SDK retries can crash the process;
-     * the driver retries a download itself instead.
-     */
-    readonly readStorage?: Storage;
-    /** Target bucket (must already exist). */
-    readonly bucket: string;
-    /** Optional object-name prefix under which all objects live (e.g. `cloudbitmaps/`). */
-    readonly prefix?: string;
-    /** Largest object this driver will write/advertise (default = GCS's 5 TiB max). Must be a positive safe integer. */
-    readonly maxObjectBytes?: number;
-    /** Bytes at/under which a single non-resumable upload is used instead of a resumable stream (default 8 MiB).
-     * Must be a positive safe integer. */
-    readonly simpleUploadThresholdBytes?: number;
-    /**
-     * Cut off a read that has run this long, in milliseconds: a tail read (with the metadata read it falls back on for
-     * an empty object) or a range read, every attempt and the backoff between them included. `0` (the default) sets no
-     * timeout. The clock starts at the call into the driver, so a credential fetch counts, and runs until the body has
-     * ended; when it passes the read throws `TransientError` and no further attempt starts. Uploads, deletes and
-     * listings are not timed. A non-negative safe integer no larger than 2,147,483,647.
-     */
-    readonly readTimeoutMs?: number;
-    /** What the backoff before re-sending a throttled upload waits on; real time when absent. */
-    readonly clock?: Sleeper;
-    /** Where the jitter of that backoff is drawn from; `Math.random` when absent. */
-    readonly rng?: Rng;
-    /**
-     * Whether a delete given `ifVersion` is sent with `ifGenerationMatch`, so it removes the object only while it is the
-     * one that generation names. Defaults to `false`, on the public endpoint too, as the registry's option does: whether
-     * real GCS applies `ifGenerationMatch` to a delete has not been verified by a run against the service, and
-     * fake-gcs-server accepts the precondition and ignores it. Set `true` once you have. Until it is set, a delete
-     * decided from one read of an object removes whatever is under the name by then: on GCS the window in which an
-     * erasure's stalled delete takes a generation a load put under the number since stays open.
-     */
-    readonly conditionalDelete?: boolean;
-}
-export declare class GcsStorageDriver implements IStorageDriver {
-    private readonly storage;
-    private readonly readStorage;
-    private readonly bucket;
-    private readonly prefix;
-    private readonly maxObjectBytes;
-    private readonly threshold;
-    private readonly readTimeoutMs;
-    private readonly clock;
-    private readonly rng;
-    private readonly presence;
-    private readonly conditionalDelete;
-    constructor(options: GcsStorageDriverOptions);
-    capabilities(): StorageCaps;
-    private file;
-    /** The same object on the download client, off the SDK's shared agent ({@link downloadFile}). */
-    private downloadable;
-    /** The deadline a read of `key` made now runs under, every attempt included, named for its error; none when off. */
-    private deadline;
-    putImmutable(key: GenKey, write: (sink: BlobSink) => Promise<void>): Promise<{
-        size: number;
-        sha256: string;
-    }>;
-    getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array>;
-    /**
-     * 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.
-     */
-    private checkRange;
-    private badRange;
-    getTail(key: GenKey, maxBytes: number): Promise<TailRead>;
-    /**
-     * The object's size from its metadata, validated, and its generation when the metadata names a usable one. 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.
-     */
-    private metadataOf;
-    /**
-     * 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.
-     */
-    private tailSize;
-    private badTail;
-    delete(key: GenKey, options?: StorageDeleteOptions): Promise<void>;
-    /** Whether an object is under the name, from its metadata. A read that fails in any other way throws. */
-    private exists;
-    list(ref: SegmentRef): AsyncIterable<GenKey>;
-    /** A read's error, once a 404 is known to be the object's and not the bucket's ({@link BucketPresence}). */
-    private readFailure;
-    /** Map GCS read errors to the driver vocabulary; pass everything else through {@link mapError}. */
-    private mapReadError;
-    /**
-     * 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, and a missing
-     * bucket as a `ValidationError` that names it; 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.
-     */
-    private mapError;
-}
-export {};