@cloudbitmaps/s3 0.19.1 → 0.21.0

package/README.md

@@ -44,7 +44,7 @@ It builds its own client from your usual AWS credentials. Any other key is refus
 | `maxSockets` | most sockets the client you do not pass opens at once, for `https` and plain `http` alike; a positive integer, default 128 (the SDK's own is 50; if a future SDK changes its handler, the built client keeps the SDK's own limit); refused beside `client` |
 | `partBytes`, `maxObjectBytes` | multipart sizing: part size (default 8 MiB; the upload buffers one part at a time) and the largest object (about 80 GiB by default, up to S3's 5 TiB). A cap above 5 TiB, or a part above S3's 5 GiB part limit, is a `ValidationError` |
 | `readTimeoutMs` | how long one read (a `GetObject` or `HeadObject`, its body included) may take before it throws `TransientError` and the store retries it; `0`, the default, sets no timeout. Writes are not timed |
-| `conditionalDelete` | whether the registry removes a deleted row with a `DeleteObject` under `If-Match` rather than leaving a tombstone. On by default when the host the client resolves is an AWS S3 host, however its endpoint was set (`endpoint`, `AWS_ENDPOINT_URL_S3`, `AWS_ENDPOINT_URL`, the shared config file); off for any other host: set it for an S3-compatible store only once you know it applies the header (MinIO ignores it) |
+| `conditionalDelete` | whether the store applies `If-Match` on a `DeleteObject`: the registry then removes a deleted row rather than leaving a tombstone, and the storage half deletes an erasure's holder only while it is the object the erasure read, by its ETag. On by default when the host the client resolves is an AWS S3 host, however its endpoint was set (`endpoint`, `AWS_ENDPOINT_URL_S3`, `AWS_ENDPOINT_URL`, the shared config file); off for any other host: set it for an S3-compatible store only once you know it applies the header (MinIO ignores it) |
 
 ## Before production
 
@@ -57,8 +57,9 @@ It builds its own client from your usual AWS credentials. Any other key is refus
   MinIO, 3.640.0 silently overwrites an existing object, which loses a published generation. `If-Match` on
   `PutObject`, which the registry's compare-and-swap is built on, is modelled from 3.700.0: 3.699.0's serializer
   omits it, so a fenced row write goes out unconditionally and can land over a concurrent writer's. This package's
-  own range never resolves below 3.700.0. The registry also checks, before its first request, that the client it is given sends `If-Match` on
-  `PutObject` and `DeleteObject`, and refuses a write it would send without its precondition.
+  own range never resolves below 3.700.0. The registry also checks, before its first request, that the client it is given sends `If-None-Match` and
+  `If-Match` on `PutObject`, and refuses a registry write it would send without its precondition; a client that does
+  not send `If-Match` on `DeleteObject` turns `conditionalDelete` off.
 - **Grant `s3:GetObject`, `s3:PutObject`, `s3:DeleteObject`, `s3:AbortMultipartUpload` and `s3:ListBucket`.** Without
   `s3:ListBucket`, S3 answers a missing key with `403` instead of `404`.
 - **Add a lifecycle rule that aborts incomplete multipart uploads**, and never one that expires current objects or the

package/dist/aws-errors.d.ts

@@ -1,10 +1,3 @@
-/**
- * SDK-free helpers for classifying AWS-style errors (used by the S3 drivers).
- *
- * These only read structural shapes an AWS SDK v3 error carries — `name`, `$metadata.httpStatusCode`, a
- * lower-level `code`/`errno`, and the SDK's own `$retryable` marker — so the (subtle, easy-to-get-wrong)
- * transient-vs-fatal decision is unit-testable without a live backend or even the SDK installed. They import no SDK.
- */
 export declare function httpStatus(err: unknown): number | undefined;
 export declare function errorName(err: unknown): string | undefined;
 /** A lower-level transport code (e.g. `ECONNRESET`) — the Node networking layer sets `code`. */
@@ -13,5 +6,8 @@ export declare function errorCode(err: unknown): string | undefined;
 export declare function isSdkRetryable(err: unknown): boolean;
 /** Any 5xx is a server-side fault that's safe to retry (the request didn't deterministically fail). */
 export declare function isServerSide(err: unknown): boolean;
-/** A dropped/timed-out connection — transient by nature; a retry on a fresh connection usually succeeds. */
+/**
+ * A dropped/timed-out connection — transient by nature; a retry on a fresh connection usually succeeds. The SDK's
+ * transport error names, the codes Node gives a failed connection ({@link isTransportFault}), and the messages above.
+ */
 export declare function isNetworkOrTimeout(err: unknown): boolean;

package/dist/backend.d.ts

@@ -89,11 +89,13 @@ export interface S3StorageOptions {
     /** Injected clock for the registry's `createdAt`/`updatedAt`; defaults to `Date.now`. */
     readonly now?: () => number;
     /**
-     * Whether the registry removes a deleted row for good, by a `DeleteObject` sent with `If-Match`, rather than leaving
-     * a tombstone a full listing reads forever. Defaults to `true` when the host the client resolves is an AWS S3 host,
-     * whichever way its endpoint was set (`endpoint`, `AWS_ENDPOINT_URL_S3`, `AWS_ENDPOINT_URL`, the shared config file),
-     * and to `false` for any other host: set it for an S3-compatible store only once you know the store applies `If-Match`
-     * on a delete. MinIO, for one, ignores it. It is never `true` for an SDK that does not send the header.
+     * Whether the store applies `If-Match` on a `DeleteObject`, which both halves rely on when it is on: 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 ETag. Defaults to `true` when
+     * the host the client resolves is an AWS S3 host, whichever way its endpoint was set (`endpoint`,
+     * `AWS_ENDPOINT_URL_S3`, `AWS_ENDPOINT_URL`, the shared config file), and to `false` for any other host: set it for an
+     * S3-compatible store only once you know the store applies `If-Match` on a delete. MinIO, for one, ignores it. It is
+     * never `true` for an SDK that does not send the header.
      */
     readonly conditionalDelete?: boolean;
 }

package/dist/bounded-body.d.ts

@@ -1,5 +1,5 @@
 /** The `GetObject` response body, narrowed to the parts used. */
-export type ResponseBody = {
+type ResponseBody = {
     transformToByteArray?: () => Promise<Uint8Array>;
     [Symbol.asyncIterator]?: () => AsyncIterator<unknown>;
     destroy?: () => void;
@@ -12,3 +12,4 @@ export declare function destroyBody(body: unknown): void;
  * propagates as it is.
  */
 export declare function readBounded(body: ResponseBody, maxBytes: number, oversize: () => Error, advertised?: number): Promise<Uint8Array>;
+export {};

package/dist/client-probe.d.ts

@@ -17,6 +17,13 @@ export declare const PROBE_KEY = "cloudbitmaps-probe";
  * found out. Never throws, never sends a request, and never runs anything the caller added to `client`.
  */
 export declare function probeClient(client: S3Client, bucket: string): Promise<ClientFacts | undefined>;
+/**
+ * Whether a `DeleteObject` may rely on `If-Match`, for the registry's row delete and the storage half's conditional
+ * delete alike: `explicit` when the caller set it, but never for an SDK seen not to send the header; otherwise only
+ * when the client resolves to an AWS S3 host, which applies the precondition, and `false` until the client has been
+ * asked, since an S3-compatible store (MinIO, for one) can accept the header and ignore it.
+ */
+export declare function appliesDeleteIfMatch(explicit: boolean | undefined, facts: ClientFacts | undefined): boolean;
 /**
  * Whether `hostname` is an AWS S3 host, by its structure: under an AWS domain, with a label that names S3 (`s3`,
  * `s3-fips`, an access point's, a multi-region access point's `s3-global`, Object Lambda's, an Outpost's, a dash-joined

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>;
+};