@cloudbitmaps/gcs 0.11.1 → 0.12.0

package/dist/storage.d.ts

@@ -1,8 +1,18 @@
 import type { BlobSink, GenKey, IStorageDriver, SegmentRef, StorageCaps } from '@cloudbitmaps/core/driver-kit';
 import type { Storage } from '@google-cloud/storage';
+/** What the throttle backoff waits on. */
+interface Sleeper {
+    sleep(ms: number): Promise<void>;
+}
 export 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/`). */
@@ -12,25 +22,62 @@ export interface GcsStorageDriverOptions {
     /** 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;
 }
 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;
     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<{
         bytes: Uint8Array;
         size: number;
     }>;
+    /**
+     * 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.
+     */
+    private sizeOf;
+    /**
+     * 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): Promise<void>;
     list(ref: SegmentRef): AsyncIterable<GenKey>;
     /** Map GCS read errors to the driver vocabulary; pass everything else through {@link mapError}. */
@@ -38,8 +85,9 @@ export declare class GcsStorageDriver implements IStorageDriver {
     /**
      * 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.
      */
     private mapError;
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbitmaps/gcs",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Google Cloud Storage for CloudBitmaps",
   "keywords": [
     "cloudbitmaps",
@@ -49,7 +49,7 @@
   },
   "dependencies": {
     "@google-cloud/storage": "^7 || ^8",
-    "@cloudbitmaps/core": "^0.11.1"
+    "@cloudbitmaps/core": "^0.12.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",