@cloudbitmaps/gcs 0.22.0 → 0.23.0

package/README.md

@@ -14,6 +14,8 @@ second service to run.
 pnpm add @cloudbitmaps/roaring @cloudbitmaps/gcs
 ```
 
+Install the same version of every `@cloudbitmaps/*` package: they release together, and each pins the exact version of `core` it was built with.
+
 `roaring` needs its one install script to fetch its native binary, and newer clients run a dependency's script only if you allow it. Allow it before you install:
 
 - **npm 12:** add `{ "allowScripts": { "roaring": true } }` to your `package.json`. Without it the install exits 0 and the package throws at `import`. npm 11 runs the script but warns until you allow it the same way.
@@ -28,6 +30,7 @@ pnpm add @cloudbitmaps/roaring @cloudbitmaps/gcs
 
 ## Use
 
+<!-- typecheck -->
 ```ts
 import { CloudRoaring } from '@cloudbitmaps/roaring';
 import { GcsStorage } from '@cloudbitmaps/gcs';
@@ -56,10 +59,18 @@ It builds its own client from Application Default Credentials. Any other key is
 
 - **This backend is outside the validated envelope.** It passes the same conformance suites as S3, but the proven
   scale and the calibration were done on S3. You are an early user.
+- **Run `await store.preflight()` once before the first load.** It writes, tries to write again, reads, lists and deletes one probe
+  object, and reads the registry and the bucket's lifecycle rules (`storage.buckets.get` for the last), and answers
+  `{ ok, checks }`. It does not check a read after a delete or versioning, among others: [the full list](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md#what-preflight-does-not-check). A first run is eight requests here.
 - **Grant the bucket's object permissions.** The library creates, reads, lists and deletes objects:
   `roles/storage.objectAdmin` covers all four.
 - **The write-once guarantee rides GCS preconditions** (`ifGenerationMatch`), so nothing else needs enabling.
 - **Never add a lifecycle rule that expires current objects or the `registry/` prefix.**
+- **Check the bucket's lifecycle rules with `await backend.checkLifecycle()`.** It reads the bucket's metadata with one
+  request (bounded by `readTimeoutMs`, when set) and answers `problem` for a `Delete` rule that applies to live objects and can match your prefix, `ok`, or
+  `unchecked`. It needs `storage.buckets.get`, which a load never uses, `store.preflight()`'s lifecycle step does, and `roles/storage.objectAdmin` does
+  not include: without it the answer is `unchecked`, naming the permission
+  ([check the lifecycle rules from code](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md#check-the-lifecycle-rules-from-code)).
 - **The SDK does not retry downloads; the driver does.** In `@google-cloud/storage` 7.x and 8.x (checked on 7.22.0 and
   8.1.0), a download the SDK retries after any status it retries (408, 429, 500, 502, 503 or 504) can crash the process
   with `ERR_STREAM_UNABLE_TO_PIPE`, thrown outside any promise, even though the retried request succeeded. The client
@@ -105,15 +116,17 @@ It builds its own client from Application Default Credentials. Any other key is
   global agent closes a connection idle for 5 seconds (the SDK's own pool does not), so a read after a longer pause
   opens a new connection, with its TCP and TLS handshake, and downloads share that agent with any other `http` or
   `https` request in the process. Raising `https.globalAgent.options.timeout` keeps idle connections longer.
-- **A transient failure of a write throws `TransientError`, and the write may or may not have landed.** Re-run the
-  call, or check `store.generations(ref)`. The driver sends each registry write once; a load that gets no answer reads
-  the row and sends a fresh compare-and-swap from it, at most three times. A generation's object of up to
-  `simpleUploadThresholdBytes` is sent again, up to three more times, only after a `429` or `503`; every object carries
-  a random id in its metadata, so a first send that landed is told from another writer's object. A load whose row writes
-  all go unanswered throws `TransientError` and keeps its object. The waits before an object's re-sends use real
-  timers: the store's injected clock does not reach them, and `GcsStorage` takes no clock, so a test that throttles
-  one object write three times waits about 3.5 s at most (the publish's waits before a fresh row write do use the
-  store's clock).
+- **A transient failure of a write throws `TransientError`, and the write may or may not have landed.** Re-run the call,
+  or check `store.generations(ref)`. The driver [sends each registry write
+  once](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/correctness.md#sdk-retry); a load that gets no
+  answer [reads the row and sends a fresh compare-and-swap from
+  it](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/correctness.md#row-write-settled), at most three
+  times. A generation's object of up to `simpleUploadThresholdBytes` is sent again, up to three more times, only after a
+  `429` or `503`; every object carries a random id in its metadata, so a first send that landed is told from another
+  writer's object. A load whose row writes all go unanswered throws `TransientError` and keeps its object. The waits
+  before an object's re-sends use real timers: the store's injected clock does not reach them, and `GcsStorage` takes no
+  clock, so a test that throttles one object write three times waits about 3.5 s at most (the publish's waits before a
+  fresh row write do use the store's clock).
 
 The [production checklist](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md) covers each item, and the ones every backend shares: backups of the data and the registry, and a schedule for your loads.
 - **The driver redacts the credentials it recognises from an error before it throws it.** The SDK keeps the response it

package/dist/backend.d.ts

@@ -1,5 +1,5 @@
 import { STORAGE_BACKEND } from '@cloudbitmaps/core/driver-kit';
-import type { IRegistryDriver, IStorageDriver, StorageBackend } from '@cloudbitmaps/core/driver-kit';
+import type { IRegistryDriver, IStorageDriver, LifecycleVerdict, StorageBackend } from '@cloudbitmaps/core/driver-kit';
 import { Storage as GcsClient } from '@google-cloud/storage';
 /**
  * What {@link GcsStorage} takes: a `bucket`, and either a `client` or the two settings that build one (`projectId`,
@@ -8,7 +8,7 @@ import { Storage as GcsClient } from '@google-cloud/storage';
 export interface GcsStorageOptions {
     /** Target bucket (must already exist). */
     readonly bucket: string;
-    /** Optional object-name prefix under which everything lives — generations and the registry alike. */
+    /** Optional object-name prefix under which everything lives — generations and the registry alike. A string, else `ValidationError`. */
     readonly prefix?: string;
     /**
      * A constructed `@google-cloud/storage` client. One is built from the ambient credentials when absent. Its retry
@@ -25,9 +25,15 @@ export interface GcsStorageOptions {
      * built, other than an interceptor, is not carried to the twin.
      */
     readonly client?: GcsClient;
-    /** Project id for the client built when `client` is absent (refused beside `client`). Falls back to the SDK's own resolution. */
+    /**
+     * Project id for the client built when `client` is absent (refused beside `client`): a non-empty string, else
+     * `ValidationError`. Falls back to the SDK's own resolution.
+     */
     readonly projectId?: string;
-    /** Endpoint override — point it at fake-gcs-server locally. Refused beside `client`, which carries its own. */
+    /**
+     * Endpoint override — point it at fake-gcs-server locally: a non-empty string, since an empty one would send
+     * requests to the public endpoint, else `ValidationError`. Refused beside `client`, which carries its own.
+     */
     readonly apiEndpoint?: string;
     /** Largest object the backend will write and advertise (default = GCS's 5 TiB max). Must be a positive safe integer. */
     readonly maxObjectBytes?: number;
@@ -88,5 +94,25 @@ export declare class GcsStorage implements StorageBackend {
     readonly registry: IRegistryDriver;
     /** The client both halves share — built here unless one was supplied. */
     readonly client: GcsClient;
+    private readonly bucket;
+    /** The name prefix every object sits under: `''`, or `trimmed/`. */
+    private readonly keyPrefix;
+    private readonly readTimeoutMs;
+    /**
+     * Builds the GCS backend over one bucket, which `bucket` names. Pass `client`, or `projectId` and `apiEndpoint` to
+     * have one built, not both. `prefix` puts every object under a name prefix. Throws `ValidationError` for an unknown
+     * option, no bucket, a `now` that is not a function, a client setting beside `client`, a `maxObjectBytes` or
+     * `simpleUploadThresholdBytes` that is not a positive integer, a `conditionalDelete` that is not a boolean, an
+     * empty or non-string `apiEndpoint` or `projectId`, or an invalid `prefix` or `readTimeoutMs`.
+     */
     constructor(options: GcsStorageOptions);
+    /**
+     * Reads the bucket's metadata (one request, plus the SDK's own retries, bounded by `readTimeoutMs` when it is set) and
+     * reports a lifecycle rule with a `Delete` action (or one it does not know) that applies to live
+     * objects whose names can be this store's: generations and registry rows alike. Needs `storage.buckets.get`, which
+     * a load never uses (`store.preflight()`'s lifecycle step does) and `roles/storage.objectAdmin` does not include: without it the answer is
+     * `unchecked`, naming the permission. Never rejects; a `detail` carries no credential. Rule reading: see the
+     * production guide.
+     */
+    checkLifecycle(): Promise<LifecycleVerdict>;
 }