@cloudbitmaps/gcs 0.19.1 → 0.21.0

package/dist/registry.d.ts

@@ -36,7 +36,7 @@
 import { ObjectStoreRegistry } from '@cloudbitmaps/core/driver-kit';
 import type { ObjectRegistryStore, ObjectRow } from '@cloudbitmaps/core/driver-kit';
 import type { Storage } from '@google-cloud/storage';
-export interface GcsRegistryDriverOptions {
+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`). */
@@ -55,8 +55,7 @@ export interface GcsRegistryDriverOptions {
     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. Only a row born with an incarnation id is removed; a row a release before
-     * 0.12 wrote is always tombstoned. Defaults to `false`, on the public endpoint too: whether real GCS applies
+     * 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.
      */
@@ -88,3 +87,4 @@ export declare class GcsRegistryStore implements ObjectRegistryStore {
 export declare class GcsRegistryDriver extends ObjectStoreRegistry {
     constructor(options: GcsRegistryDriverOptions);
 }
+export {};

package/dist/storage.d.ts

@@ -1,10 +1,9 @@
-import type { BlobSink, GenKey, IStorageDriver, SegmentRef, StorageCaps } from '@cloudbitmaps/core/driver-kit';
+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. */
-interface Sleeper {
-    sleep(ms: number): Promise<void>;
-}
-export interface GcsStorageDriverOptions {
+type Sleeper = Pick<Clock, 'sleep'>;
+interface GcsStorageDriverOptions {
     /** A constructed `@google-cloud/storage` `Storage` client (point `apiEndpoint` at fake-gcs-server locally). */
     readonly storage: Storage;
     /**
@@ -32,6 +31,17 @@ export interface GcsStorageDriverOptions {
     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;
@@ -42,7 +52,9 @@ export declare class GcsStorageDriver implements IStorageDriver {
     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;
@@ -63,15 +75,13 @@ export declare class GcsStorageDriver implements IStorageDriver {
      */
     private checkRange;
     private badRange;
-    getTail(key: GenKey, maxBytes: number): Promise<{
-        bytes: Uint8Array;
-        size: number;
-    }>;
+    getTail(key: GenKey, maxBytes: number): Promise<TailRead>;
     /**
-     * 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.
+     * 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 sizeOf;
+    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;
@@ -79,17 +89,20 @@ export declare class GcsStorageDriver implements IStorageDriver {
      */
     private tailSize;
     private badTail;
-    delete(key: GenKey): Promise<void>;
+    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;
-     * 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.
+     * 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;
 }

package/package.json

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

package/dist/keys.d.ts

@@ -1,31 +0,0 @@
-/**
- * Logical-ref → GCS object-name mapping for {@link GcsStorageDriver}.
- *
- * Pure string logic, no SDK dependency — unit-testable without GCS or an emulator. Uses the **same
- * backend-agnostic `.crbm` object-name scheme** as the S3 + LocalFs storage drivers
- * (`<prefix><ns>/segments/<segment>.<gen>.crbm`), so a segment reads identically whichever storage backend holds
- * it. The default (absent) namespace maps to `_default`, which cannot collide with a real namespace because a
- * caller's `_default` encodes to `%5Fdefault` while the sentinel is emitted literally.
- *
- * The storage-key layout is shared, not copied: `prefixPart` and the name encoders come from
- * `@cloudbitmaps/core/driver-kit`, so a segment written by one driver reads identically under another. Two
- * drivers disagreeing about how a name becomes a key would be a silent cross-driver incompatibility on the
- * same bucket, which is exactly the kind of thing a local copy drifts into.
- */
-import type { GenKey, SegmentRef } from '@cloudbitmaps/core/driver-kit';
-/** Validate a caller-supplied key prefix. The rule is shared with every other object store. */
-export { normalizeObjectPrefix as normalizeGcsPrefix } from '@cloudbitmaps/core/driver-kit';
-/**
- * The GCS object-name prefix shared by all of a segment's generations: `<prefix><ns>/segments/<segment>.`.
- * Used both as the `getFiles` prefix and as the string stripped by {@link parseGenerationFromName}.
- */
-export declare function segmentObjectPrefix(prefix: string | undefined, ref: SegmentRef): string;
-/** The full GCS object name of one `.crbm` generation: `<segmentPrefix><gen>.crbm`. */
-export declare function storageObjectName(prefix: string | undefined, key: GenKey): string;
-/**
- * Parse a generation number out of a full object name, given its segment prefix, or `null` if it doesn't
- * match. Canonical decimal only — no leading zeros (so `…s.07.crbm` can't alias `…s.7.crbm`) and within
- * safe-integer range. Also rejects a *different* segment whose name merely shares the prefix (its middle
- * isn't all digits).
- */
-export declare function parseGenerationFromName(segmentPrefix: string, objectName: string): number | null;