@cloudbitmaps/gcs 0.11.2 → 0.13.0

package/dist/storage.d.ts

@@ -1,5 +1,9 @@
 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;
@@ -18,6 +22,16 @@ 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;
@@ -26,21 +40,36 @@ export declare class GcsStorageDriver implements IStorageDriver {
     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. */
+    /** 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. */
+    /**
+     * 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
@@ -61,3 +90,4 @@ export declare class GcsStorageDriver implements IStorageDriver {
      */
     private mapError;
 }
+export {};

package/package.json

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