@cloudbitmaps/gcs 0.19.1 → 0.21.0

package/README.md

@@ -43,7 +43,7 @@ It builds its own client from Application Default Credentials. Any other key is
 | `projectId`, `apiEndpoint` | build a client for you, such as one for fake-gcs-server; refused beside `client` |
 | `simpleUploadThresholdBytes`, `maxObjectBytes` | the size up to which an object is one simple request (default 8 MiB) and the largest object (default 5 TiB, GCS's maximum) |
 | `readTimeoutMs` | cut off a read that has run this long, in milliseconds (see below); `0`, the default, sets no timeout |
-| `conditionalDelete` | whether the registry removes a deleted row with an object delete under `ifGenerationMatch`, rather than leaving a tombstone every full listing reads. Off by default, 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 ignores it, so CI cannot show it. Set `true` to remove rows for good. Needs delete permission on the registry prefix |
+| `conditionalDelete` | whether the service applies `ifGenerationMatch` on an object delete: the registry then removes a deleted row rather than leaving a tombstone every full listing reads, and the storage half deletes an erasure's holder only while it is the object the erasure read, by its generation. Off by default, 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 ignores it, so CI cannot show it. Set `true` to remove rows for good, and to close, on GCS, the window in which an erasure's stalled delete takes a generation a load put under the number since: while it is off, that window stays open. Needs delete permission on the registry prefix |
 
 ## Before production
 

package/dist/backend.d.ts

@@ -61,10 +61,13 @@ export interface GcsStorageOptions {
      */
     readonly readTimeoutMs?: number;
     /**
-     * Whether the registry removes a deleted row for good, by an object delete sent with `ifGenerationMatch`, rather
-     * than leaving a tombstone a full listing reads forever. 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.
+     * Whether the service applies `ifGenerationMatch` on an object delete, which both halves rely on when it is set: the
+     * registry removes a deleted row for good rather than leaving a tombstone a full listing reads forever, and the
+     * storage half removes an erasure's holder only while it is the object the erasure searched, by its generation.
+     * 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` once you know it does. Until then, the window in which an erasure's stalled delete
+     * takes a generation a load put under the number since stays open on GCS.
      */
     readonly conditionalDelete?: boolean;
 }

package/dist/bucket-presence.d.ts

@@ -12,7 +12,7 @@
  *                                              ▼
  *                              list one object in the bucket
  *                               ├─ answered ──────────▶ remember the bucket; the 404 is an object's
- *                               ├─ 404 ───────────────▶ reject: the bucket does not exist
+ *                               ├─ 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)
@@ -31,7 +31,7 @@ export declare class BucketPresence {
     private settled;
     private asking;
     constructor(storage: Storage, bucket: string);
-    /** Resolve when a 404 can be read as an object's; reject when the bucket does not exist or the listing failed in transit. */
+    /** 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/defined.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `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/gcs-errors.d.ts

@@ -7,6 +7,7 @@
  * `.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.
@@ -27,9 +28,17 @@ export declare function isNotFound(err: unknown): boolean;
  * 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: one of {@link TRANSPORT_CODES}. */
+/** 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
@@ -44,3 +53,8 @@ export declare function isDownloadRetryable(err: unknown): boolean;
  * 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;